Installing#
Which Python?#
You’ll need Python 3.10 or greater.
The recommended way to install Python depends on your experience: Are you new to
the Python packaging ecosystem or already got experience with it? If you already
know what conda
and pip
are, and are able to install tedious packages
GIS packages yourself without issue, you are experienced. If you have no idea
what the previous sentence was about, you are new.
New#
We recommend new users to install iMOD Python using the Deltaforge Python distribution. See Installing with Deltaforge.
Experienced#
For experienced users, who want to be in control of packages installed, we recommend installing using pixi. Pixi supports creating reproducible projects, where all dependencies’ versions in an environment are stored in a textfile, the “lockfile”. On top of that, it is faster than other package managers.
Alternatively, you can use the Miniforge Python distribution. This installs
the conda
package manager. This installer differs from the also
commonly-used Miniconda installer, in a nutshell:
Miniforge is a community driven installers, installing by default from the
conda-forge
channel (Pixi also does this).Miniconda is a company driven installer, installing by default from the
anaconda
channel.Installing from the
anaconda
channel has certain (legal) limitations for “commercial use”, especially if you work in a large organization.
Installing Pixi/Mambaforge/Miniforge/Miniconda does not require administrative rights to your computer and doesn’t interfere with any other Python installations in your system.
Dependencies#
The imod
Python package makes extensive use of the modern scientific Python
ecosystem. The most important dependencies are listed here.
Data structures:
Delayed/out-of-core computation, parallellization:
Spatial operations:
Geospatial libaries (optional):
Data provisioning for examples:
Visualization:
pyvista (Optional)
Installing all these dependencies requires around 2.5 gigabyte of space; Installing only the required dependencies (via pip) requires around 0.5 gigabyte.
Ways to install iMOD Python#
Installing with Deltaforge#
Deltaforge is an installer of Deltares python packages, including iMOD Python, and their dependencies. This makes it possible to install iMOD Python without much knowledge about the Python package management system. The download links are listed here. Users new to the python package ecosystem are recommended to install iMOD Python using Deltaforge.
Installing with pixi#
Pixi supports creating reproducible projects, where all dependencies’ versions in an environment are stored in a textfile, the “lockfile”. On top of that, it is faster than other package managers. Installing with pixi is fast and easy:
pixi init my_project
cd my_project
pixi add imod
You can activate your environment using:
pixi shell
These commands create a pixi.toml
and a pixi.lock
. The pixi.toml
contains the dependencies of your project. If you followed the commands above,
the only dependency present in the toml should be imod
. The pixi.lock
is
a textfile that captures the environment in a specific state, so all
dependencies, with their dependencies and so on, with exact version numbers.
This is very useful, as it allows you to get the exact same environment on a
different machine, by just copying two textfiles. The lockfile will be updated
if you run pixi update
or change the pixi.toml
file. Both the
pixi.toml
as well as the pixi.lock
are required to fully reproduce an
environment.
Installing with conda#
Alternatively, you can also use the conda package manager. We advice to
install imod
in a seperate conda
environment, as you can simply delete
these in case they break. Not doing so will install imod and its dependencies in
your base environment, which requires a reinstall of Miniforge in case this
environment breaks:
conda create -n imodenv
conda install -n imodenv imod --channel conda-forge
conda
will automatically find the appropriate versions of the dependencies
and in this case install them in the imodenv
environment. Installing with
conda will automatically download all optional dependencies, and
enable all functionality.
To run scripts using imod
, you first have to activate the imodenv
environment:
conda activate imodenv
Installing with pip#
Finally, you can also use the pip package manager:
pip install imod
Unlike installing with conda, installing with pip will not install all optional dependencies. This results in a far smaller installation, but it means that not all functionality is directly available.
Refer to Installing Python and packages in the FAQ section for background
information on conda
, and pip
.
Installing the latest development version#
You can use pip
to install the latest source from GitHub:
pip install git+https://github.com/Deltares/imod-python.git
Alternatively, you can clone the git repository locally and install from there:
git clone https://github.com/Deltares/imod-python.git
cd imod-python
pip install -e .