Installation

Installation#

The probably-too-simple moonshot install:

pipx install floodsr

Basic Install#

floodsr comes in two flavours:

  • basic install: for rasters less than ~2 billion pixels or ~25 sq. km. (assuming a 1m target resolution)

  • extended install: for rasters too large for memory. If you think you need this (and are feeling brave), skip ahead to Extended Install.

As floodsr is a simple pypi distributed python package, it can be installed in a variety of contexts. Here we provide instructions for the three most common:

Command line (CLI)#

A command-line interface (CLI) means running commands in a terminal instead of clicking through a graphical app. floodsr was designed as a CLI-first Python package, so we recommend installing with pipx for simple environment isolation. For this, you need a working Python 3.12+ and pip (which usually comes already shipped with Python). After this, 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 from the warning.

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 command line (CLI), which you can use to validate the install. Start with the help command to confirm the command line (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.

Local notebook (Jupyter)#

Running floodsr in a local notebook environment is a nice way to process individual rasters interactively and visualize the results. To do this, you need to have Jupyter installed in a Python 3.12+ environment.

Check your Python and Jupyter setup by running the following in a terminal:

python --version
python -m jupyter --version

Then, you can install floodsr with pip and register a dedicated Jupyter kernel for it:

python -m pip install floodsr ipykernel
python -m ipykernel install --user --name floodsr --display-name "Python (floodsr)"

Then launch Jupyter from that environment:

python -m jupyter lab

Note

Alternatively, for a quick and lazy one-time use install (nice for tutorials), you can run the following from inside a running kernel (i.e., notebook cell):

%pip install floodsr

But this can lead to messy environments and is not recommended for regular use.

Finally, confirm the CLI is available from the notebook:

!floodsr doctor

Hosted notebook (Colab)#

Google Colab is a popular hosted notebook environment that provides a nice web-based interface with common libraries pre-installed, which makes it great for quick experiments or interactive tutorials. However, patching in new packages (like floodsr) can be a bit tricky, so we don’t recommend this for regular use.

To setup a Colab notebook for floodsr, launch Google Colab in your browser and login with your Google account. Then, create a new notebook and add the following to the first cell:

!python -m pip install -q floodsr

Finally, confirm the CLI is available from the notebook:

!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.

Command line (CLI) - Extended#

The popular conda package manager is the easiest way to build an isolated environment with GDAL. 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

Then confirm the GDAL-backed environment is active:

floodsr doctor

You should see something like gdal_config_installed=True.

Local notebook (Jupyter) - Extended#

Follow the same Command line (CLI) - Extended instructions to set up your GDAL-backed floodsr environment, then install Jupyter into that same environment and register a dedicated kernel:

python -m pip install jupyterlab ipykernel
python -m ipykernel install --user --name floodsr-gdal --display-name "Python (floodsr-gdal)"

Then launch Jupyter from that environment and select the “Python (floodsr-gdal)” kernel:

python -m jupyter lab

Finally, confirm the GDAL-backed environment is active from the notebook:

!floodsr doctor

Hosted notebook (Colab) - Extended#

While Colab is nice for standard environments, GDAL is not standard… so the extended floodsr with GDAL install is finnicky and probably won’t work. For the foolhardy, the below seems to be working as of March 2026, but this will probably break when Colab updates their base images so maybe don’t waste your time:

# setup an experimental GDAL environment in Colab
!apt-get update -qq
!apt-get install -y -qq gdal-bin libgdal-dev
!pip install -q --upgrade pip
!pip install -q "gdal[numpy]==$(gdal-config --version).*" rasterio geopandas pyproj shapely fiona

# install floodsr
!pip install -q floodsr