pywatershed

• About
• Installation
• Getting started / Example notebooks
• Community engagement
• How to Cite
• Disclaimer

About

Welcome to the pywatershed repository!

Pywatershed is Python package for simulating hydrologic processes motivated by the need to modernize important, legacy hydrologic models at the USGS, particularly the Precipitation-Runoff Modeling System (PRMS, Markstrom et al., 2015) and its role in GSFLOW (Markstrom et al., 2008). The goal of modernization is to make these legacy models more flexible as process representations, to support testing of alternative hydrologic process conceptualizations, and to facilitate the incorporation of cutting edge modeling techniques and data sources. Pywatershed is a place for experimentation with software design, process representation, and data fusion in the context of well-established hydrologic process modeling.

For more information on the goals and status of pywatershed, please see the pywatershed docs.

Installation

pywatershed uses Python 3.12.

The pywatershed package is available on PyPI but installation of all dependencies sets (lint, test, optional, doc, and all) may not be reliable on all platforms.

The pywatershed package is available on conda-forge. The installation is the quickest way to get up and running by provides only the minimal set of dependencies (not including Jupyter nor all packages needed for running the example notebooks, also not suitable for development purposes).

We recommend the following installation procedures to get fully-functional environments for running pywatershed and its example notebooks. We strongly recommend using Mambato first instal dependencies from the environment_y_jupyter.yml file in the repository before installing pywatershed itself. Mamba will be much faster than Ananconda (but the conda command could also be used).

If you wish to use the stable release, you will use main in place of <branch> in the following commands. If you want to follow development, you'll use develop instead.

Without using git (directly), you may:

curl -L -O https://raw.githubusercontent.com/DOI-USGS/pywatershed/<branch>/environment_w_jupyter.yml
mamba env create -f environment_w_jupyter.yml
mamba activate pws
pip install git+https://github.com/DOI-USGS/pywatershed.git@<branch>

Or to use git and to be able to develop:

git clone https://github.com/DOI-USGS/pywatershed.git
cd pywatershed
mamba env create -f environment_w_jupyter.yml
mamba activate pws
pip install -e .

(If you want to name the environment other than the default pws, use the command mamba env update --name your_env_name --file environment_w_jupyter.yml --prune you will also need to activate this environment by name.)

We install the environment_w_jupyter.yml to provide all known dependencies including those for running the example notebooks.

Getting started / Example notebooks

Please note that you can browse the API reference, developer info, and index in the pywatershed docs. But the best way to get started with pywatershed is to dive into the example notebooks.

For introductory example notebooks, look in the examples/ directory in the repository. Numbered starting at 00, these are meant to be completed in order. Numbered starting at 00, these are meant to be completed in order. Notebook outputs are not saved in Github.

Non-numbered notebooks in examples/ cover additional topics. These notebooks are not yet covered by testing and you may encounter some issues. In examples/developer/ there are notebooks of interest to developers who may want to learn about running the software tests.

Community engagement

We value your feedback! Please use discussions or issues on Github. For more in-depth contributions, please start by reading over the pywatershed DEVELOPER.md and CONTRIBUTING.md guidelines.

Thank you for your interest.

How to Cite

McCreight, J. L., Langevin, C. D., Hughes, J. D., & Bonelli, W. P. (2026). pywatershed (Version 3.0.0) [Computer software]. https://doi.org/10.5066/P13RCHPY

Disclaimer

This software has been approved for release by the U.S. Geological Survey (USGS). Although the software has been subjected to rigorous review, the USGS reserves the right to update the software as needed pursuant to further analysis and review. No warranty, expressed or implied, is made by the USGS or the U.S. Government as to the functionality of the software and related material nor shall the fact of release constitute any such warranty. Furthermore, the software is released on condition that neither the USGS nor the U.S. Government shall be held liable for any damages resulting from its authorized or unauthorized use.