Installation for users

Capytaine requires Python 3.8 or higher. It is regularly tested on Windows, MacOS and Linux using all currently supported version of Python

Precompiled packages are distributed for Windows, MacOS (both Intel and ARM processors) and Linux for all supported versions of Python. However, it might take a few weeks before precompiled packages for the latest version of Python (3.13 at the time of writing) are available and you might prefer using an earlier version of Python.

On a cloud platform

For a quick try of Capytaine without installing anything on your computer, you can use an online Python-based computing environment such as CoCalc, on which Capytaine is already installed by default, or Google Colab. On such a Jupyter-based environment, Capytaine can be installed by running the following command in a cell:

%pip install capytaine

Then run the following line to check which version of Capytaine has been installed:

import capytaine as cpt; print(cpt.__version__)

You may need to restart the computing environment (kernel) of the notebook for the installation to be effective.

All the core feature of Capytaine are accessible from such a Jupyter-based environment, except for some 3D visualization tools.

As a standalone executable

An experimental distribution of Capytaine bundled with a full Python distribution in a single executable file can be found at https://github.com/capytaine/capytaine-standalone. Please refer to the instruction on that page for download and usage.

The standalone executable is the simplest way to use Capytaine locally, although it has some limitations, such a longer startup time and the current lack of interactive Matplotlib figures.

You can check the bundled version of Capytaine with the following command:

.\ipython-with-capytaine-windows.exe -c 'print(cpt.__version__)'

(or the corresponding file name on other platforms than Windows).

Installing with pip package manager

Since version 2.0, Capytaine is available as precompiled package on all platforms on PyPI, the package registry used by the pip command. After installing a Python interpreter, run the following command line in a terminal to install Capytaine and its dependencies:

python -m pip install capytaine

Then run the following line to check that the latest version of Capytaine has been installed:

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

You might want to use a virtual environment to install Capytaine independently of your other Python packages and avoid any risk of dependency conflict.

The package can also be installed by other modern PyPI-based Python package managers, such as UV, PDM or poetry. Below is an example command to run a Python script in an environment created on the fly by UV:

uv run --with capytaine my_script.py

Installing with Conda package manager

Capytaine is also available in the Anaconda package repository, that can be accessed with the Anaconda distribution or one of its lightweight counterparts Miniconda and Miniforge.

Note

If you experience very long processing time when installing a package with conda, you might want to install the libmamba solver or fully replace conda with Mamba.

Once Conda has been installed, you can install Capytaine from the conda-forge channel. It is recommended to do the installation into a dedicated virtual environment (here arbitrarily named capytaine_env):

conda create --name capytaine_env --channel conda-forge capytaine

Then activate the environment to use it on the command line with:

conda activate capytaine_env

or set it in the project configuration of your IDE (for instance see the documentation of PyCharm, the documentation of VSCode or the documentation of Spyder).

Alternatively, Capytaine can be installed in an existing environment with the following command:

conda install --channel conda-forge capytaine

You can check which version of Capytaine has been installed by running the following command line:

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

The latest version is currently 2.2.1.

Optional dependencies

All the required dependencies should be installed automatically when installing with pip or conda. More optional dependencies can be manually installed. They are nice to have but not necessary for Capytaine’s main features.

Name	Example installation command	Usage
matplotlib	pip install matplotlib	Used in several examples in the documentation and the cookbook
vtk	pip install vtk	For 3D visualization
meshio	pip install meshio	To load more mesh formats
netcdf4	pip install meshio	To export in NetCDF4 format
joblib	pip install joblib	For parallel resolution

After creating the Conda environment containing Capytaine, you can add more packages to this environment by activating it with conda activate and then using the conda install or pip install commands. However, it is often more efficient to specify the packages you’d like in your environment from the start when creating it, such as in the following example:

conda create --name capy_and_other_env --channel conda-forge capytaine jupyter matplotlib vtk

More build recipes

More advanced build recipes for Capytaine are available in the dedicated repository `https://github.com/capytaine/capytaine-extra-build-recipes`_. In particular, build recipes for Docker and Guix might be useful for reproducible computations.