README.md

Installation • Documentation

earthkit-hydro is a Python library for common hydrological functions. It is the hydrological component of earthkit.

Main Features

• Catchment delineation
• Catchment-based statistics
• Directional flow-based accumulations
• River network distance calculations
• Upstream/downstream field propagation
• Bifurcation handling
• Custom weighting and decay support
• Support for PCRaster, CaMa-Flood, HydroSHEDS, MERIT-Hydro and GRIT river network formats
• Compatible with major array-backends: xarray, numpy, cupy, torch, jax, mlx and tensorflow
• GPU support
• Differentiable operations suitable for machine learning

Installation

For a default installation, run

pip install earthkit-hydro

Developer instructions:

For a developer setup (includes linting and test libraries), run

conda create -n hydro python=3.12
conda activate hydro
conda install -c conda-forge rust
git clone https://github.com/ecmwf/earthkit-hydro.git
cd earthkit-hydro
pip install -e .[dev]
pre-commit install

Note: this project is a mixed Rust-Python project with a pure Python fallback. To handle this, the behaviour of the install is based on an environmental variable USE_RUST, with the following behaviour

• Not set or any other value (default behaviour): Attempts to build with Rust and if failure, skips and falls back to pure Python implementation.
• USE_RUST=0: Builds pure Python implementation.
• USE_RUST=1: Builds with Rust and fails if something goes wrong.

Licence

SPDX-FileCopyrightText: 2026- European Centre for Medium-Range Weather Forecasts (ECMWF)
SPDX-License-Identifier: Apache-2.0

See LICENSE for the full licence text, including ECMWF's intergovernmental notice.

Citing

If you use earthkit-hydro in your work, please consider citing

Morrison, O. M. and Carton de Wiart, C.: Introducing earthkit-hydro: an efficient graph-based library for scalable hydrological modelling and analysis, EGU General Assembly 2026, Vienna, Austria, 3–8 May 2026, EGU26-11233, https://doi.org/10.5194/egusphere-egu26-11233, 2026.

@inproceedings{Morrison2026,
  author    = {Morrison, Ois{\'\i}n M. and Carton de Wiart, Corentin},
  title     = {Introducing earthkit-hydro: an efficient graph-based library for scalable hydrological modelling and analysis},
  booktitle = {EGU General Assembly 2026},
  year      = {2026},
  series    = {EGU General Assembly Conference Abstracts},
  volume    = {EGU26-11233},
  address   = {Vienna, Austria},
  month     = may,
  doi       = {10.5194/egusphere-egu26-11233},
  url       = {https://doi.org/10.5194/egusphere-egu26-11233}
}