Installation for developers

The development of Capytaine mostly happens on Linux or Windows Subsystem for Linux (WSL). You can find below some instructions to compile Capytaine on macOS or Windows. These instruction are not updated regularly and might be out-of-date. Please open an issue on Github if you need help.

Previous versions of this documentation recommended the use of Conda (or Mamba) to develop Capytaine. This is not really necessary on Linux, where it might be simpler and faster to use a PyPI-based workflow. Conda might nonetheless be useful on Windows in order to install development tools such as git, just or gfortran.

Installation for development using pip on Linux or WSL

As of February 2025, the build backend used by Capytaine since version 2.0 (meson-python) is not fully compatible with some modern tools such as uv for development (see https://github.com/astral-sh/uv/issues/10214).

You might need to have Python installed as well as common development tools such as git, gfortran and just. On Ubuntu or Debian, this can be done with:

sudo apt install python3 python3-pip python3-venv python-is-python3 git gfortran just

Not that just is only available in this way in recent versions of Ubuntu (24.04 and newer) and Debian (13 and newer).

Get the source code from Github using git:

git clone https://github.com/capytaine/capytaine
cd capytaine

If you wish to contribute to the project, you might want to create a fork of the project and clone it using the SSH interface (see Github’s documentation for more details). Let us create a virtual environment in which the development version of Capytaine and its dependencies will be installed, such as:

python -m venv /tmp/capy_dev_venv

Note that the build-system used by Capytaine does not like the use of virtual environment in the same directory as the source code (https://github.com/capytaine/capytaine/issues/396).

Activate the virtual environment with:

source /tmp/capy_dev_venv/bin/activate  # with bash shell, change accordingly for other shell

To prepare the development environment, we’ll install the required dependencies. Assuming you have a recent enough version of pip, this can be done with:

pip install --group editable_install

and then build Capytaine in editable mode:

pip install --no-build-isolation --editable .

The above two commands can also be executed by typing:

just editable_install

As long as the virtual environment is activated, every import of Capytaine in Python will use the development version in this directory. All change made to the source code should automatically affects the installed package. (You may need to restart you Python interpreter, but rerunning pip install should not be necessary.)

Call for instance the following line to check that Capytaine has been correctly installed:

python -c 'import capytaine as cpt; print(cpt.__version__)'

Installation for development using Conda

If you are for instance on Windows, it is recommended to use Conda (or the alternative implementation with the same user interface Mamba) as package manager and virtual environment manager to install Capytaine for development. Let us first create a new virtual environment with:

conda create --name capy_dev python pip
conda activate capy_dev

By default, Conda will install the latest version of Python.

If git is not available in your environment, you can install it through conda:

conda install -c conda-forge git

Then the source code can be downloaded using git with:

git clone https://github.com/capytaine/capytaine
cd capytaine

Alternatively, the source code can be directly downloaded from Github web interface.

Several options are available to get a Fortran compiler. Please choose below the most relevant to your case.

GFortran compiler on Linux or Windows Subsystem for Linux

You can install gfortran with the package manager of your distribution. For instance on Debian or Ubuntu:

sudo apt install gfortran

Alternatively, gfortran is also available from the conda-forge channel of the Conda package repository:

conda install -c conda-forge gfortran
GFortran compiler on macOS

You can install gfortran via Homebrew:

brew install gcc

Make sure that the compilers installed by Homebrew are in you path (e.g., which gcc); this can be accomplished by adding the relevant directories to your path:

export PATH="/usr/local/bin:$PATH"

or through the use of aliases, e.g.,:

alias gcc=/usr/local/bin/gcc-10
GFortran on Windows

The GNU toolchain, including gfortran can be installed with the help of conda:

conda install -c conda-forge m2w64-toolchain
Intel compiler on Windows

Microsoft Visual Studio is required for linking the Fortran binaries

Intel oneAPI HPC toolkit is required for compiling the Fortran binaries (you do not need the base kit)

Create a LIB environment variable to point towards the intel directory for compiler .lib files

  • If oneAPI is installed to the default location, assign the LIB user variable a value of:

    C:\Program Files (x86)\Intel\oneAPI\compiler\2022.1.0\windows\compiler\lib\intel64_win

  • If oneAPI is installed to a different location then adjust the path above as necessary

Test if your Fortran compiler was installed correctly by entering ifort on your command line

Once you have a Fortran compiler installed, the same instructions as above can be used to install the Python dependencies of Capytaine:

pip install --group editable_install

and then build Capytaine in editable mode:

pip install --no-build-isolation --editable .

If just is not available in your environment, you can install it through conda:

conda install -c conda-forge just

and simply use the following line to install Capytaine in editable mode in your conda environment:

just editable_install

You can check that the package is installed by running:

python -c 'import capytaine as cpt; print(cpt.__version__)'

Building the documentation

In a pip or conda virtual environment (which can be the same as above or a different one), install Capytaine with the extra dependencies docs:

pip install --group docs
pip install .[optional]

Then run the make command in the docs/ directory:

make --directory="./docs/"

and the documentation will be built in the docs/_build directory.

Alternatively, use:

just build_docs