Python Installation#

Arbor’s Python API will be the most convenient interface for most users.


Arbor requires Python version 3.7 and later. It is advised that you update pip as well. We strongly encourage using pip to install Arbor.

To get help in case of problems installing with pip, run pip with the --verbose flag, and attach the output (along with the pip command itself) to a ticket on Arbor’s issues page.

Getting Arbor#

Every point release of Arbor is pushed to the Python Package Index. For x86-64 Linux and MacOS platforms, we provide binary wheels. The easiest way to get Arbor is with pip:

# Recommended but optional: install Arbor in a virtual environment
python -m venv arbor_env
source arbor_env/bin/activate
# Download and install Arbor
pip install arbor

To test that Arbor is available, try the following in a Python interpreter to see information about the version and enabled features:

>>> import arbor
>>> arbor.print_config()

You are now ready to use Arbor! You can continue reading these documentation pages, have a look at the Python API reference, or visit the Tutorials.


For builds from Arbor’s source, you will need to have some development packages installed. Installing Arbor for any other platforms than listed above, pip will attempt a build from source and thus require these packages as well.

  • Ubuntu/Debian: git cmake gcc python3-dev python3-pip

  • Fedora/CentOS/OpenSuse: git cmake gcc-c++ python3-devel python3-pip

  • MacOS: get brew at and run brew install cmake clang python3

  • Windows: the simplest way is to use WSL and then follow the instructions for Ubuntu.

Customising Arbor#

If you wish to get the latest Arbor straight from the master branch in our git repository, you can run:

pip install git+

If you want to work on Arbor’s code, you can get a copy of our repo and point pip at the local directory:

# get your copy of the Arbor source
git clone --recursive
# make your changes and then instruct pip to build and install the local source
pip install ./arbor/

Every time you make changes to the code, you’ll have to repeat the second step.

Advanced options#

Arbor comes with a few compilation options, some of them related to advanced forms of parallelism and other features. The options and flags are the same as documented for the CMAKE build, but they are passed differently. To enable more, they must be placed in the CMAKE_ARGS environment variable. The simplest way to do this is by prepending the pip command with CMAKE_ARGS="", where you place the arguments separated by space inside the quotes.

The following flags can be used to configure the installation:

  • ARB_WITH_MPI=<ON|OFF>: Enable MPI support, requires MPI library. Default OFF. If you intend to use mpi4py, you need to install the package before building Arbor, as binding it requires access to its headers.

  • ARB_GPU=<none|cuda|cuda-clang|hip>: Enable GPU support for NVIDIA GPUs with nvcc using cuda, or with clang using cuda-clang (both require cudaruntime). Enable GPU support for AMD GPUs with hipcc using hip. By default set to none, which disables GPU support.

  • ARB_VECTORIZE=<ON|OFF>: Enable vectorization. The architecture argument, documented below, may also have to be set appropriately to generated vectorized code. See Architecture for details.

  • ARB_ARCH=<native|*>: CPU micro-architecture to target. The advised default is native. See the GNU GCC documentation for a full list of options.


There are more, advanced flags that can be set. We are using scikit-build-core and CMake under the hood, so all flags and options valid in CMake can be used in this fashion.

Detailed instructions on how to install using CMake are in the Python configuration section of the installation guide. CMake is recommended if you need more control over compilation and installation, plan to use Arbor with C++, or if you are integrating with package managers such as Spack and EasyBuild.

In the examples below we assume you are installing from a local copy.

Vanilla install with no additional features enabled:

pip install ./arbor

With MPI support. This might require loading an MPI module or setting the CC and CXX environment variables:

CMAKE_ARGS="-DARB_WITH_MPI=ON" pip install ./arbor

Compile with vectorization on a system with a SkyLake architecture:

CMAKE_ARGS="-DARB_VECTORIZE=ON -DARB_ARCH=skylake" pip install ./arbor

Enable NVIDIA GPUs (compiled with nvcc). This requires the CUDA toolkit:

CMAKE_ARGS="-DARB_GPU=cuda" pip install ./arbor

Enable NVIDIA GPUs (compiled with clang). This also requires the CUDA toolkit:

CMAKE_ARGS="-DARB_GPU=cuda-clang" pip install ./arbor

Enable AMD GPUs (compiled with hipcc). This requires setting the CC and CXX environment variables:

CC=clang CXX=hipcc CMAKE_ARGS="-DARB_GPU=hip" pip install ./arbor

Note on performance#

The Python interface can incur significant memory and runtime overheads relative to C++ during the model building phase, however simulation performance is the same for both interfaces.