Install#

Install HydroModPy with the package manager you already use. Pick a tab, run the command, you are ready to go.

Want to contribute, build the docs, or run the test suite?

This page covers the user install. For the editable clone, the pre-commit hooks, the Sphinx toolchain, or the WSL/PETSc developer environment, head over to the contributor install in the developer section.

Quick install#

pip install --pre hydromodpy

This documentation targets the v2 alpha line. The --pre flag is needed while v2 is published as 2.0.0aN, 2.0.0bN, or 2.0.0rcN. Without --pre, pip install hydromodpy installs the latest stable release from PyPI. The two CLI entry points become available straight away:

hmp --version
hmp --help

Need an IDE bundle (Spyder + JupyterLab)? Use pip install --pre "hydromodpy[ide]" instead. The full list of optional extras is below. The default install includes the optuna calibration sampler used by the Nancon calibration example.

Choose your installer#

pip + venv

The lightest path. Works on any supported Python interpreter (3.11, 3.12, or 3.13).

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install --pre hydromodpy

On Windows PowerShell, replace the first two lines with py -3.12 -m venv .venv and .\.venv\Scripts\Activate.ps1.

uv

uv is a fast, drop-in replacement for pip. Recommended when bootstrapping a fresh environment or a CI job.

uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install --pre hydromodpy

One-shot run without a long-lived venv:

uvx --from hydromodpy hmp --help

conda

Recommended when geospatial libraries are tricky to build from source (Windows, restricted environments). A minimal env is enough:

conda create -n hmp python=3.12 pip
conda activate hmp
pip install --pre hydromodpy

For the curated environment YAMLs (runtime stack, with Spyder and the geospatial dependencies), download the file you need from the install/ folder on GitHub, then create the env from the downloaded copy:

conda env create -n hmp -f env_hydromodpy.yml
conda activate hmp

docker

Truly zero local install: only Docker (or Podman) is required on the host. No clone, no Python, no pip.

Pull from the registry (recommended):

docker run --rm ghcr.io/hydromodpy/hydromodpy --help

Hosted image: coming soon

The official hydromodpy image will be published on the GitHub Container Registry at ghcr.io/hydromodpy/hydromodpy once the publish step is enabled in the CI. Until then, use the local build below.

Local build (works today):

git clone https://github.com/HydroModPy/HydroModPy.git
cd HydroModPy
docker build -t hydromodpy .
docker run --rm hydromodpy --help

Solver binaries are not embedded in the image. They are pulled into the container on the first solver run, into the cache under the hmp user home.

conda-forge

Coming soon

A hydromodpy feedstock on conda-forge is being prepared. In the meantime, use the conda tab above with env_hydromodpy.yml from the install/ folder on GitHub, or fall back to pip inside a conda env.

Optional extras#

HydroModPy ships a few optional extras. Add only what you need; combine them inside one pip install command, for example pip install "hydromodpy[ide,viewer3d]".

Extra	Provides
`[ide]`	`ipykernel`, `jupyterlab`, Spyder, and PySide6.
`[viewer3d]`	`pyvista` for 3D mesh visualization.
`[calibration]`	`cma` and `cmaes` for CMA-ES calibration variants. The default `optuna` TPE sampler is installed by the base package.
`[test]`	`pytest`, `pytest-xdist`, `pytest-timeout`, `coverage` for running the test tiers.
`[dev]`	`ruff` and `pre-commit` for linting and Git hooks. Contributor-only.
`[docs]`	Sphinx, the PyData theme, `myst-parser`, `nbsphinx`, plus the extensions used to build this documentation. Pure wheels, no system Graphviz needed. Contributor-only.
`[docs-uml]`	`erdantic` to regenerate the config ER diagrams. Needs a system Graphviz install; `pygraphviz` has no wheels. Contributor-only.

The [dev] and [docs] extras belong to the contributor flow. See Contribute for the editable clone and the full developer setup.

Verify the install#

Once installed, this short snippet imports the public surface and prints the version:

import hydromodpy
from hydromodpy.config import HydroModPyConfig
from hydromodpy.display import list_figures

print("hydromodpy", hydromodpy.__version__)
print("first 3 figures:", [spec.name for spec in list_figures()[:3]])

If the imports succeed, you are ready to follow Getting Started for the first guided run, or Cookbook for short TOML-first recipes.

Upgrade#

pip install --upgrade hydromodpy

The same command works inside a uv-managed venv, a conda env, or any other PEP 668 compliant environment.

Where next#

First run

Concepts in five minutes, then a guided end-to-end project on a real basin.

Getting Started

Cookbook

Short TOML-first recipes for the most common HydroModPy tasks.

Cookbook

Contribute

Editable clone, pre-commit hooks, [dev,test,docs] extras, WSL/PETSc helpers, and the documentation toolchain.

Contribute

Solver binaries#

MODFLOW, MODPATH, and MT3D-USGS executables are downloaded on demand the first time a solver runs, into ~/.cache/hydromodpy/bin/ (or the platform equivalent). Override the location with the HMP_BIN environment variable.

In most cases nothing is required from the user: the first solver run populates the cache transparently. The dropdown below covers the explicit commands and the air-gapped flow.