Installation#

PyBaMM is available on GNU/Linux, MacOS and Windows. It can be installed using uv, pip, or conda, or from source.

Prerequisites#

To use PyBaMM, you must have Python 3.10 - 3.14 installed.

Debian-based distributions (Debian, Ubuntu)

To install Python 3 on Debian-based distributions (Debian, Ubuntu), open a terminal and run

sudo apt-get update
sudo apt-get install python3

macOS

On macOS, you can use the homebrew package manager. First, install brew:

ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

then follow instructions in the link on adding brew to path, and run

brew install python

Windows

To install Python 3, download the installation files from Python’s website. Make sure to tick the box on Add Python 3.X to PATH. For more detailed instructions please see the official Python on Windows guide.

Virtual environment#

We recommend installing PyBaMM within a virtual environment, in order not to alter any distribution Python files.

To create a virtual environment within your current directory:

uv

uv venv

This creates a .venv directory. You can then “activate” the environment using:

GNU/Linux and macOS

source .venv/bin/activate

Windows

.venv\Scripts\activate.bat

pip

GNU/Linux and macOS

virtualenv env

You can then “activate” the environment using:

source env/bin/activate

Windows

First install virtualenv:

python -m pip install virtualenv

Then create a virtual environment:

python -m virtualenv env

You can then “activate” the environment using:

env\Scripts\activate.bat

When you are ready to exit the environment and go back to your original system, just type:

deactivate

For an introduction to virtual environments, see (https://realpython.com/python-virtual-environments-a-primer/).

Install PyBaMM#

uv

PyBaMM can be installed via uv from PyPI.

uv pip install pybamm

pip

PyBaMM can be installed via pip from PyPI.

pip install pybamm

conda

PyBaMM is available as a conda package through the conda-forge channel.

Warning

PyBaMM versions between 24.11.2 and 25.6 (not including these boundary versions) are not available on conda-forge.

The pybamm-base package installs PyBaMM with its required dependencies only:

conda install -c conda-forge pybamm-base

The pybamm package installs PyBaMM with all optional dependencies except jax:

conda install -c conda-forge pybamm

To optionally install jax, see Optional - JaxSolver.

PyBaMM’s required dependencies (such as numpy, casadi, etc) will be installed automatically when you install pybamm using pip or pybamm-base using conda.

Optional - JaxSolver#

Users can install pybamm with jax and jaxlib to use the Jax solver.

uv

uv pip install "pybamm[jax]"

pip

pip install "pybamm[jax]"

conda

conda install -c conda-forge "jax>=0.7.0,<0.9.0"

Uninstall PyBaMM#

PyBaMM can be uninstalled by running

uv

uv pip uninstall pybamm

pip

pip uninstall pybamm

conda

conda remove pybamm

in your virtual environment.

Dependencies#

PyBaMM requires the following dependencies:

Warning

The list of dependencies below might be outdated. Users are advised to manually check the pyproject.toml file to find out supported versions.

Required dependencies#

PyBaMM requires the following dependencies.

Package	Supported version(s)
PyBaMM solvers	>= 0.8.0, <0.9.0
NumPy	Whatever recent versions work
SciPy	Whatever recent versions work. >= 1.11.4
CasADi	Whatever recent versions work (transitive via pybammsolvers)
Xarray	Whatever recent versions work. >= 2022.6.0
Anytree	Whatever recent versions work. >= 2.8.0
SymPy	Whatever recent versions work. >= 1.12
typing-extensions	Whatever recent versions work. >= 4.10.0
pandas	Whatever recent versions work. >= 1.5.0
pooch	Whatever recent versions work. >= 1.8.1
posthog	Whatever recent versions work
black
pyyaml
platformdirs

Optional Dependencies#

PyBaMM has a number of optional dependencies for different functionalities. If the optional dependency is not installed, PyBaMM will raise an ImportError when the method requiring that dependency is called.

If you are using pip, optional PyBaMM dependencies can be installed or managed in a file (e.g., pyproject.toml) as optional extras (e.g.,``pybamm[plot,cite]``). All optional dependencies can be installed with pybamm[all], and specific sets of dependencies are listed in the sections below.

Plot dependencies#

Installable with pip install "pybamm[plot]"

Dependency	Minimum Version	pip extra	Notes
matplotlib	3.6.0	plot	To plot various battery models, and analyzing battery performance.

Docs dependencies#

Installable with pip install --group docs or uv sync --group docs

Dependency	Minimum Version	group	Notes
sphinx	-	docs	Sphinx makes it easy to create intelligent and beautiful documentation.
sphinx_rtd_theme	-	docs	This Sphinx theme provides a great reader experience for documentation.
pydata-sphinx-theme	-	docs	A clean, Bootstrap-based Sphinx theme.
sphinx_design	-	docs	A sphinx extension for designing.
sphinx-copybutton	-	docs	To copy codeblocks.
myst-parser	-	docs	For technical & scientific documentation.
sphinx-inline-tabs	-	docs	Add inline tabbed content to your Sphinx documentation.
sphinxcontrib-bibtex	-	docs	For BibTeX citations.
sphinx-autobuild	-	docs	For re-building docs once triggered.
sphinx-last-updated-by-git	-	docs	To get the “last updated” time for each Sphinx page from Git.
nbsphinx	-	docs	Sphinx extension that provides a source parser for .ipynb files
ipykernel	-	docs	Provides the IPython kernel for Jupyter.
ipywidgets	-	docs	Interactive HTML widgets for Jupyter notebooks and the IPython kernel.
sphinx-gallery	-	docs	Builds an HTML gallery of examples from any set of Python scripts.
sphinx-docsearch	-	docs	To replaces Sphinx’s built-in search with Algolia DocSearch.

Examples dependencies#

Installable with pip install "pybamm[examples]"

Dependency	Minimum Version	pip extra	Notes
jupyter	-	examples	For example notebooks rendering.

Dev dependencies#

Installable with pip install --group dev or uv sync --group dev

Dependency	Minimum Version	group	Notes
pre-commit	-	dev	For managing and maintaining multi-language pre-commit hooks.
ruff	-	dev	For code formatting.
nox	-	dev	For running testing sessions in multiple environments.
pytest-cov	-	dev	For calculating test coverage.
pytest	9.0.0	dev	For running the test suites (includes subtests support).
pytest-doctestplus	-	dev	For running doctests.
pytest-xdist	-	dev	For running tests in parallel across distributed workers.
pytest-mock	-	dev	Provides a mocker fixture.
nbmake	-	dev	A `pytest` plugin for executing Jupyter notebooks.
pytest-snapshot	-	dev	For snapshot testing.
hypothesis	-	dev	Used to perform property based testing.

Cite dependencies#

Installable with pip install "pybamm[cite]"

Dependency	Minimum Version	pip extra	Notes
pybtex	0.25.0	cite	BibTeX-compatible bibliography processor.

bpx dependencies#

Installable with pip install "pybamm[bpx]"

Dependency	Minimum Version	pip extra	Notes
bpx	1.1.0	bpx	Battery Parameter eXchange

tqdm dependencies#

Installable with pip install "pybamm[tqdm]"

Dependency	Minimum Version	pip extra	Notes
tqdm	-	tqdm	For logging loops.

Jax dependencies#

Installable with pip install "pybamm[jax]", currently supported on Python 3.11-3.14.

Dependency	Minimum Version	pip extra	Notes
JAX	0.7.0	jax	For the JAX solver

Installing from source#

Installing a specific version? Installing from source? Check the advanced installation pages below.