Install from source (Docker)#

This page describes the build and installation of PyBaMM using a Dockerfile, available on GitHub. Note that this is not the recommended approach for most users and should be reserved to people wanting to participate in the development of PyBaMM, or people who really need to use bleeding-edge feature(s) not yet available in the latest released version. If you do not fall in the two previous categories, you would be better off installing PyBaMM using pip or conda.


Before you begin, make sure you have Docker installed on your system. You can download and install Docker from the official Docker website. Ensure Docker installation by running:

docker --version

Pulling the Docker image#

Use the following command to pull the PyBaMM Docker image from Docker Hub:

docker pull pybamm/pybamm:latest
docker pull pybamm/pybamm:odes
docker pull pybamm/pybamm:jax
docker pull pybamm/pybamm:idaklu
docker pull pybamm/pybamm:all

Running the Docker container#

Once you have pulled the Docker image, you can run a Docker container with the PyBaMM environment:

  1. In your terminal, use the following command to start a Docker container from the pulled image:

docker run -it pybamm/pybamm:latest
docker run -it pybamm/pybamm:odes
docker run -it pybamm/pybamm:jax
docker run -it pybamm/pybamm:idaklu
docker run -it pybamm/pybamm:all
  1. You will now be inside the Docker container’s shell. You can use PyBaMM and its dependencies as if you were in a virtual environment.

  2. You can execute PyBaMM-related commands, run tests develop & contribute from the container.

Exiting the Docker container#

To exit the Docker container’s shell, you can simply type:


This will return you to your host machine’s terminal.

Building Docker image locally from source#

If you want to build the PyBaMM Docker image locally from the PyBaMM source code, follow these steps:

  1. Clone the PyBaMM GitHub repository to your local machine if you haven’t already:

git clone
  1. Change into the PyBaMM directory:

cd PyBaMM
  1. Build the Docker image using the following command:

docker build -t pybamm -f scripts/Dockerfile .
  1. Once the image is built, you can run a Docker container using:

docker run -it pybamm
  1. Activate PyBaMM development environment inside docker container using:

conda activate pybamm

Building Docker images with optional arguments#

When building the PyBaMM Docker images locally, you have the option to include specific solvers by using optional arguments. These solvers include:

  • IDAKLU: For IDA solver provided by the SUNDIALS plus KLU.

  • ODES: For scikits.odes solver for ODE & DAE problems.

  • JAX: For Jax solver.

  • ALL: For all the above solvers.

To build the Docker images with optional arguments, you can follow these steps for each solver:

docker build -t pybamm:odes -f scripts/Dockerfile --build-arg ODES=true .
docker build -t pybamm:jax -f scripts/Dockerfile --build-arg JAX=true .
docker build -t pybamm:idaklu -f scripts/Dockerfile --build-arg IDAKLU=true .
docker build -t pybamm:all -f scripts/Dockerfile --build-arg ALL=true .

After building the Docker images with the desired solvers, use the docker run command followed by the desired image name. For example, to run a container from the image built with all optional solvers:

docker run -it pybamm:all

Activate PyBaMM development environment inside docker container using:

conda activate pybamm

If you want to exit the Docker container’s shell, you can simply type:


Using Git inside a running Docker container#


You might require re-configuring git while running the docker container for the first time. You can run git config --list to ensure if you have desired git configuration already.

  1. Setting up git configuration

git config --global "Your Name"

git config --global
  1. Setting a git remote

git remote set-url origin <fork_url>

git remote add upstream

git fetch --all

Using Visual Studio Code inside a running Docker container#

You can easily use Visual Studio Code inside a running Docker container by attaching it directly. This provides a seamless development environment within the container. Here’s how:

  1. Install the “Docker” extension from Microsoft in your local Visual Studio Code if it’s not already installed.

  2. Pull and run the Docker image containing PyBaMM development environment.

  3. In your local Visual Studio Code, open the “Docker” extension by clicking on the Docker icon in the sidebar.

  4. Under the “Containers” section, you’ll see a list of running containers. Right-click the running PyBaMM container.

  5. Select “Attach Visual Studio Code” from the context menu.

  6. Visual Studio Code will now connect to the container, and a new VS Code window will open up, running inside the container. You can now edit, debug, and work on your code using VS Code as if you were working directly on your local machine.