1.1. Installation#


pyGIMLi is available for Windows, macOS, and Linux and can be installed via various package managers:

pip install pygimli

uv add pygimli

conda install -c gimli -c conda-forge pygimli

pixi add --channel gimli --channel conda-forge pygimli

While we do not have a preference on the package manager you use, we recommend to avoid mixing them and generally encourage the use of separated environments, which will be discussed for pip and conda below.

1.1.1. Installing via pip#

pip is the default command to install Python packages. On most systems pip ships together with Python, so installing a Python 3 is usually all you need:

Install Python with the official python.org installer and tick “Add python.exe to PATH” during setup, or install it from the Microsoft Store.

Recent macOS versions no longer ship Python. Install it with the official python.org installer or via Homebrew:

brew install python

Python is preinstalled on most distributions. Install Python, pip and venv via your package manager, e.g.:

sudo apt install python3 python3-pip python3-venv    # Debian/Ubuntu
sudo dnf install python3 python3-pip                 # Fedora
sudo pacman -S python python-pip                     # Arch

Verify that everything is available (use py instead of python3 on Windows):

python3 --version
python3 -m pip --version

To avoid conflicts with other packages we install pyGIMLi into a separate environment, here called pg (you can pick any name; the environment only has to be created once).

python -m venv .venv --prompt=pg
.venv/Scripts/activate

python -m venv .venv --prompt=pg
source .venv/bin/activate

python -m venv .venv --prompt=pg
source .venv/bin/activate

To install pygimli:

pip install pygimli

To update pygimli:

pip install -U pygimli

Find available versions:

pip index versions pygimli

To install a specific version:

pip install pygimli==x.x.x

1.1.2. Installing via conda/mamba#

We recommend to install the conda/mamba package managers via the lightweight and free Miniforge distribution (https://conda-forge.org/download/).

# These two lines are optional but recommended
conda create -n pg
conda activate pg

conda install -c gimli pygimli

Once the environment is activated you can use pyGIMLi from the command line with your editor of choice. To activate it automatically in every new terminal, add the activation command (conda activate pg) to your shell startup file, e.g. ~/.bashrc.

1.1.3. Using pyGIMLi with Spyder or JupyterLab#

Depending on your preferences, you can also install third-party software such as the MATLAB-like integrated development environment Spyder:

conda install -c conda-forge spyder

Or alternatively, the web-based IDE JupyterLab:

conda install -c conda-forge jupyterlab

If you do one of the above steps in the pg environment, then it will automatically find pyGIMLi. But you may not want to install JupyterLab or Spyder for every different environment. To use your existing JupyterLab installation in the base environment with pyGIMLi in the pg environment, follow these steps:

conda activate pg
conda install ipykernel
conda activate base
conda install -c conda-forge nb_conda_kernels
jupyter lab

1.1.4. pyGIMLi on Google Colab#

Even though still experimental, pyGIMLi can be run on Google Colab without any installation on your own computer. Just create a new notebook and install the pyGIMLi package via pip:

!pip install pygimli tetgen

Some preinstalled packages may pull in an incompatible NumPy version, so you might have to uninstall them first:

!pip uninstall -y numba tensorflow pytensor thinc
!pip install pygimli tetgen

1.1.5. Staying up-to-date#

Update your pyGIMLi installation from time to time to get the newest functionality:

pip install -U pygimli

conda update -c gimli -c conda-forge pygimli

If something went wrong and you are running an old, no longer supported Python version, consider a fresh install in a new clean environment.

1.1.6. Development version#

The conda packages follow our release rhythm. To work with the latest Python code from git while still using the pre-built C++ core, first create an environment with only pgcore:

python -m venv .venv --prompt pgcore
source .venv/bin/activate # Mac/Linux
.venv/Scripts/activate # windows
pip install pgcore

conda create -n pgcore -c gimli -c conda-forge pgcore
conda activate pgcore

Retrieve the source code with git:

git clone https://github.com/gimli-org/gimli
cd gimli

and install pyGIMLi as an editable (development) package:

pip install --no-build-isolation --no-deps -e .

conda develop .

Alternatively you could set the PYTHONPATH variable, but then you would have to take care of dependencies yourself. Later you can update the pyGIMLi code with:

git pull

Only if you need recent changes to the C++ core itself do you have to compile pyGIMLi with your system toolchain, as described in the build guide.