Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Installation

Pywr is both a Rust library and a Python package.

Rust

The Rust CLI is available from a checkout of the repository. Install a Rust toolchain, initialise the bundled solver submodules, and run the following from the repository root:

git submodule update --init --recursive
cargo run --release -p pywr-cli -- --help

The Python package does not install the separate Rust CLI. See the README for source-build requirements.

Python

Pywr v2 requires Python 3.11 or later. The first release candidate is 2.0.0rc1 (not yet the stable v2 release). Use a separate virtual environment if you also use v1.x. To remain on v1.x, install it with python -m pip install "pywr<2" instead.

Installing from PyPI

Using pip and venv

It is recommended to install Pywr into a virtual environment.

python -m venv .venv
source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`
python -m pip install --upgrade "pywr>=2.0.0rc1,<3"

Using uv

Alternatively, you can use uv to create and manage virtual environments:

uv init my-project
cd my-project
uv add "pywr>=2.0.0rc1,<3"

The version constraint selects v2 rather than v1.x. Once the stable v2 release is published, install it with python -m pip install --upgrade "pywr>=2,<3". Optional extras for data integrations include pandas, polars, excel and hdf; for example, use "pywr[pandas,excel]>=2.0.0rc1,<3" with the pip command above.

Installing from a wheel

Use PyPI as the primary source of release wheels. Wheel builds target Linux x86-64, Windows x64, and macOS Intel and Apple Silicon. If you need a wheel from a development build, download the relevant artifact from GitHub Actions, extract it, and install the .whl file compatible with your Python version and platform using python -m pip install /path/to/downloaded.whl. If no compatible wheel is available, installation requires a source build and native build tools.

Checking the installation

To verify the installation, show the Python CLI help:

python -m pywr --help

Running a model

Pywr is a modelling system for simulating water resources systems. Models are defined using a JSON schema and can be run using the Python CLI. Below is an example of a simple model definition simple1.json:

{
  "metadata": {
    "title": "Simple 1",
    "description": "A very simple example.",
    "minimum_version": "0.1"
  },
  "time": {
    "start": "2015-01-01",
    "end": "2015-12-31",
    "timestep": {
      "type": "Days",
      "days": 1
    }
  },
  "network": {
    "nodes": [
      {
        "meta": {
          "name": "supply1"
        },
        "type": "Input",
        "max_flow": {
          "type": "Literal",
          "value": 15.0
        }
      },
      {
        "meta": {
          "name": "link1"
        },
        "type": "Link"
      },
      {
        "meta": {
          "name": "demand1"
        },
        "type": "Output",
        "max_flow": {
          "type": "Parameter",
          "name": "demand"
        },
        "cost": {
          "type": "Literal",
          "value": -10
        }
      }
    ],
    "edges": [
      {
        "from_node": "supply1",
        "to_node": "link1"
      },
      {
        "from_node": "link1",
        "to_node": "demand1"
      }
    ],
    "parameters": [
      {
        "meta": {
          "name": "demand"
        },
        "type": "Constant",
        "value": {
          "type": "Literal",
          "value": 10.0
        }
      }
    ],
    "metric_sets": [
      {
        "meta": {"name": "all"},
        "filters": {
          "all_nodes": true,
          "all_virtual_nodes": true,
          "all_parameters": true,
          "all_edges": true
        }
      }
    ],
    "outputs": [
      {
        "meta": {"name": "all"},
        "type": "Memory",
        "metric_set": "all"
      },
      {
        "meta": {"name": "all-hdf5"},
        "type": "HDF5",
        "filename": "outputs.h5",
        "metric_set": "all"
      }
    ]
  }
}

To run the model, use the Python CLI:

python -m pywr run simple1.json