Installation

A bit-too-simple moonshot install:

pipx install floodsr

pipx command not found? Check System Requirements. Running in Google Colab? Jump to Basic Install (Google Colab).

System Requirements

floodsr was designed as a CLI-first Python package, so we recommend installing with pipx to ensure environment isolation (except for Google Colab, where pip is the better fit. See Basic Install (Google Colab)). This project requires Python 3.12+ and pip (which usually comes shipped with Python). Once you have a compatible Python install, installing pipx is easy. If you have a modern Python setup, installing pipx is easy:

python -m pip install --user pipx
python -m pipx ensurepath

If you see a warning about needing to do something for PATH changes to take effect, follow the instructions.

Basic Install

Check pipx is installed and on the PATH:

pipx --version

Then install floodsr with pipx:

pipx install floodsr

If you see a message like installed package floodsr, you’re g2g and should have access to the floodsr CLI, which you can use to validate the install. Start with the help command to confirm the CLI is working:

floodsr --help

You can also try the doctor command to echo the current environment and floodsr configuration:

floodsr doctor

This should show the version and status of the backends used by floodsr.

Basic Install (Google Colab)

Google Colab already gives you an isolated Python environment, so pipx is unnecessary there. Install the core package with pip in a notebook cell:

python -m pip install floodsr

Then confirm the CLI is available:

!floodsr --help

Extended Install

For handling rasters too large for memory, floodsr uses GDAL backends. To enable these features, install floodsr into an environment with GDAL. The popular conda package manager is the easiest way to do this. The best way to install conda is via the open-source Miniforge project, NOT the proprietary Anaconda distribution.

Once you have conda installed, use it to create a dedicated environment with GDAL, activate it, then install floodsr with pip into that same environment:

conda create -n floodsr-gdal -c conda-forge python=3.12 gdal -y
conda activate floodsr-gdal
python -m pip install floodsr

Now the doctor command should report GDAL Python bindings as installed and VRT support as enabled:

floodsr doctor

Good job. You deserve some hi-res flood rasters now.