pysteps turns a radar extrapolation into an ensemble you can verify

Two audiences sharing one library, and the difference between them

pysteps is described as an open-source and community-driven Python library for probabilistic precipitation nowcasting, that is, short-term ensemble prediction systems.

The stated aim is to serve two different needs, and reading them together tells you how the library is shaped. The first is to provide a modular and well-documented framework for researchers interested in developing new methods for nowcasting and stochastic space-time simulation of precipitation. The second is to offer a highly configurable and easily accessible platform for practitioners ranging from weather forecasters to hydrologists.

A researcher and a duty forecaster want opposite things from an API. The researcher wants to swap out the advection method, replace the noise generator and see how the ensemble statistics change. The forecaster wants a stable pipeline with sensible defaults and a plot at the end. pysteps tries to serve both, and the cost of that is the API surface you see in the reference documentation, which is large.

The domain is worth understanding before the code. Nowcasting here means extrapolating precipitation fields forward from radar observations over a short horizon, typically minutes rather than days, and doing it probabilistically so you get a distribution of possible futures rather than one deterministic animation. The topic list on the repository spells out the components: advection, ensemble-prediction, forecast-verification, hydrology, nowcasting, optical-flow, precipitation, stochastic-processes and weather-radar.

If you want a forecast that says how much rain will fall in an hour over a catchment, this is the right kind of library. If you want a numerical weather prediction model, it is not.

Optical flow plus stochastic generators, which is the actual method

The library supports standard input and output file formats and implements several optical flow methods as well as advanced stochastic generators to produce ensemble nowcasts. In addition it includes tools for visualizing and post-processing the nowcasts, and methods for deterministic, probabilistic and neighbourhood forecast verification.

That enumeration is the method in three sentences. The optical flow step estimates the motion field of the precipitation pattern from consecutive radar frames, and advection moves the field forward using that motion. The stochastic generator step is what turns a single extrapolation into an ensemble: it perturbs the field so each member explores a slightly different realisation of the uncertain growth and decay of the pattern. Without that step you have a deterministic nowcast, which is the thing the framework is designed to move past.

The distinction between the three verification methods is worth a line each, because choosing the wrong one is how people get misleading numbers. Deterministic verification scores the forecast against what happened at each lead time. Probabilistic verification scores the distribution, whether the observation fell in the ensemble, using proper scores. Neighbourhood verification relaxes the requirement of a point match and instead asks whether the forecast was right somewhere in a neighbourhood of the observed point, which is the right question when you are verifying at a different spatial resolution from the one you forecast at.

The repository examples show the breadth of what is implemented. There are files for optical flow methods, for noise generators, for the cascade decomposition, for the anvil nowcast, for a thunderstorm detection and tracking example, and for the Linda nowcasts, alongside the ensemble verification and probability forecast examples.

Installation needs a compiler, and the build tells you why

The recommended installation is through conda from the conda-forge channel:

    $ conda install -c conda-forge pysteps

conda rather than pip is the recommendation, and the reason is visible in the build configuration. The pyproject.toml build system requires wheel, setuptools 40.8.0 or newer, Cython 0.29.2 or newer, and numpy 1.13 or newer, and the setup.py file defines two Cython extensions for the motion module, pysteps.motion._proesmans and pysteps.motion._vet, with the sources given as .pyx files and cythonize called with force=True and language_level=3.

So the package compiles Cython extensions at install time, with -O3 and -ffast-math in the compile flags and OpenMP enabled, and there is a special link path for macOS to point at the Homebrew GCC runtime. That is a real installation, not a wheel download, and the conda route handles the toolchain for you.

The runtime requirements in requirements.txt are the usual scientific stack: numpy, opencv-python, pillow, pyproj, scipy, matplotlib, jsmin, jsonschema and netCDF4. The presence of pyproj and netCDF4 tells you the library works with projected coordinates and with NetCDF, which is the file format most radar and satellite products ship in, and opencv-python is there for the image handling in the optical flow step.

The project also ships environment.yml and environment_dev.yml for Conda users, a tox.ini for multi-environment testing, and a .pre-commit-config.yaml. The documentation points to an installation guide for the full details, and to a separate pysteps-data repository holding example radar data, with a page explaining how to download and install it.

Start with the notebook before you start with the API

The quick start is a Colab notebook, and that choice tells you something about how the library is meant to be learned.

The project documentation suggests using pysteps to compute and plot a radar extrapolation nowcast in Google Colab with an interactive notebook called my_first_nowcast. The repository contains that file at examples/my_first_nowcast.ipynb, along with a README.txt in the examples directory and a substantial set of Python examples covering the whole surface: optical flow, noise generators, the extrapolation nowcast, the STEPS nowcast, the Linda and anvil nowcasts, probability forecasts, ensemble verification, linear blending, advection correction, rainfarm downscaling, data transformations, custom precipitation ranges, cascade decomposition, thunderstorm detection and tracking, the Kalman filter blended forecast and the steps blended forecast.

The naming gives you a good map of the algorithm families. The extrapolation nowcast is the basic optical flow approach. The STEPS nowcast is the stochastic generator ensemble, which is the main event. The Linda and anvil nowcasts are specialised variants, with the anvil one aimed at convective cell tracking. The blending examples combine nowcasts with numerical weather prediction or with a Kalman filter, which is how practitioners get the benefits of a short-range extrapolation together with the skill of a physical model.

There is also a gallery of examples on the documentation site and a full API reference page, both linked from the top-level documentation. The documentation is hosted on readthedocs with a stable version, and the package publishes a Zenodo DOI badge for citation.

The nowcast itself is documented in two peer reviewed papers

For a project in this area, the citation record is the most reliable quality signal, and pysteps has two of them rather than one.

The overall library is described in Pulkkinen, Nerini, Perez Hortal, Velasco-Forero, Germann, Seed and Foresti, 2019, titled Pysteps: an open-source Python library for probabilistic precipitation nowcasting (v1.0), in Geoscientific Model Development, volume 12, issue 10, pages 4185 to 4219, with the DOI 10.5194/gmd-12-4185-2019.

The more recent blending module is described in Imhoff, De Cruz, Dewettinck, Brauer, Uijlenhoet, van Heeringen, Velasco-Forero, Nerini, Van Ginderachter and Weerts, 2023, titled Scale-dependent blending of ensemble rainfall nowcasts and NWP in the open-source pysteps library, in the Quarterly Journal of the Royal Meteorological Society, pages 1 to 30, with the DOI 10.1002/qj.4461.

The gap between the two papers is instructive. The first describes the library as it was, the second describes a module added afterwards that scales with distance, meaning the blending behaves differently for nearby and distant targets. That is a research library in the honest sense: methods are added as they are published, and the reference is the literature.

The repository carries a CITATION.bib file at the root for that purpose, and a Zenodo badge points at a concept DOI that covers all versions rather than a single release, which is the correct choice for a library with a long citation history.

BSD-3-Clause, frequent releases, and two things the readme does not say

The licence is BSD-3-Clause, and the badge points at the OSI's BSD 3-Clause text. For a scientific library that most users install as a dependency rather than vendor, that is the expected choice.

Upkeep is the healthiest part of the picture. The last push was on 2026-10-08, and the release history shows v1.21.5 on 2026-08-14, v1.21.4 on 2026-08-10 and v1.21.3 on 2026-08-03. Three patch releases in a fortnight is the pattern of a project with continuous integration and an active review queue, and the badges in the project documentation confirm the shape, with separate workflows for the test suite and for a Black formatting check, plus coverage and Codacy badges.

Two things the top-level documentation does not say are worth flagging, because you will discover them yourself otherwise.

The first is the install requirement. Nothing in the top-level documentation mentions that a C compiler, Cython and OpenMP are needed, and the conda recommendation is the only hint. If you are on a locked-down cluster with a system Python, that install will not work and you need to know that before you plan around it.

The second is the scope of the verification. The documentation lists the three verification methods as features of the library, but it does not tell you which metrics to use for a given application, nor does it mention anything about how the library handles the radar data quality issues that are the hardest part of real nowcasting, such as clutter or attenuation. The examples and the reference documentation are where you will look, and both are outside the top-level documentation.

The repository also carries a bandit.yaml file at the root, which is the configuration for the Python security linter, suggesting the project runs static security analysis as part of its checks.

Editorial conclusion

pysteps suits a hydrology or meteorology group that needs a verified probabilistic nowcast rather than a single deterministic image, and that already works in Python and can install a compiled extension. It is the wrong choice for a forecast that must be operational on a strict schedule without human review, since nothing in the documentation addresses run-time guarantees, and the wrong choice if you want a single deterministic extrapolation, because the framework's centre of gravity is the ensemble. Before adopting it, run the my_first_nowcast notebook on the pysteps-data example radar to see the full loop end to end, and read the verification modules, because the framework is only as good as the way you measure it.

Frequently asked questions

Official sources

1. License: BSD-3-Clause
2. Project website
3. pySTEPS/pysteps on GitHub
4. README
5. Releases