Python (Installation)

The exercises at Hydro-Informatics use scientific and geospatial Python packages. Install these packages in a separate environment to control dependencies and avoid modifying the operating system’s Python installation.

• Use Miniforge and conda-forge for the course environment, including flusstools, on Windows, Linux, and macOS.

• Use pip + venv for exercises that do not require native GDAL libraries.

• Retain environment specifications and record the versions used for each project.

conda / mamba¶

Quick Guide (Miniforge)¶

1. Install Miniforge3 for your operating system and processor architecture. On Windows, open Miniforge Prompt. On Linux/macOS, allow shell initialization during installation and reopen the terminal.

2. Download the flusstools environment.yml. Open a terminal in the download directory and create the environment:

   conda env create -f environment.yml
   conda activate flussenv

   Use Python 3.11–3.13 for this specification. Its NumPy/SciPy dependencies require at least Python 3.11, and it excludes Python 3.14. The file includes JupyterLab and the geospatial stack; it is partly pinned, rather than an exact lockfile.

3. Install flusstools from PyPI after the conda dependencies:

   python -m pip install flusstools
   python -m pip check

4. Check the GDAL Python bindings, NumPy raster support, and flusstools:

   python -c "from osgeo import gdal, gdal_array; import flusstools as ft; print(gdal.VersionInfo('--version'))"

   An import error indicates an incomplete or incompatible installation. See the flusstools installation documentation.

The Python project template provides a separate project structure. Its environment file installs local project code and must be used from the complete repository; downloading that YAML alone is insufficient. Use the flusstools specification above for this guide.

pip + venv on Linux Mint/Ubuntu¶

Install the Distribution’s Interpreter¶

sudo apt update
sudo apt install python3 python3-venv

These commands install the distribution’s Python version, which must satisfy the exercise’s dependencies.

Create & Activate an Environment¶

python3 -m venv ~/venvs/vflussenv
source ~/venvs/vflussenv/bin/activate
python -m pip install --upgrade pip

A default venv isolates installed Python packages; it does not provide native libraries such as GDAL.

Install Requirements¶

For exercises without GDAL:

python -m pip install numpy pandas scipy matplotlib seaborn
python -m pip check

If an exercise provides a requirements.txt, check its Python and package constraints, then install it with python -m pip install -r requirements.txt.

Install flusstools¶

Use the conda environment above for flusstools. A venv installation additionally requires GDAL ≥3.10, development headers, and Python bindings matching the native GDAL version. Installing libgdal-dev from an older distribution does not necessarily satisfy these requirements. See the GDAL Python installation instructions before attempting a source build.

GDAL on Windows and Other Platforms¶

Official GDAL releases on PyPI currently provide source distributions. Rasterio and Fiona wheels may include their own GDAL libraries, but they do not supply the separately imported osgeo bindings required by flusstools. Use conda-forge for this course’s geospatial environment on all three operating systems.

Install Extra Packages with pip¶

Run pip through the active interpreter:

python -m pip install seaborn

This example applies to a venv. In a conda environment, add available dependencies to environment.yml and create a replacement environment as described below. Install conda packages first and pip-only packages, including flusstools, last. See conda’s guidance on using pip.

Bulk Install¶

Keep project dependencies in a reviewed requirements.txt (venv) or environment.yml (conda). Preserve tested constraints when recording an analysis; replacing every exact version with >= does not establish compatibility.

Install Jupyter Kernel¶

Register the interpreter used for the exercises:

conda activate flussenv
python -m ipykernel install --user --name fluss_kernel --display-name "Python (flussenv)"

source ~/venvs/vflussenv/bin/activate
python -m pip install jupyterlab ipykernel
python -m ipykernel install --user --name vfluss_kernel --display-name "Python (vflussenv)"

In JupyterLab, select the corresponding display name under Kernel > Change Kernel. In a notebook, import sys; print(sys.executable) identifies the kernel’s interpreter.

Update Environments¶

Update Virtual Environment (venv)¶

Record the installed versions, inspect available updates, and upgrade only the packages required for the project:

source ~/venvs/vflussenv/bin/activate
python -m pip freeze > requirements-before.txt
python -m pip list --outdated
python -m pip install --upgrade jupyterlab
python -m pip check

Run the exercise notebooks before recording a revised specification. A freeze file records Python distributions; it does not capture native libraries or guarantee rollback. Recreate an environment from the previous tested specification if needed.

Update conda Environment¶

Record the current environment before reviewing changes to environment.yml:

conda env export -n flussenv > environment-before.yml
conda list -n flussenv --explicit > conda-explicit-before.txt

The YAML records conda and pip packages. Explicit conda specifications identify platform-specific builds and exclude pip-only packages; neither file alone guarantees complete reproducibility.

Create a replacement under a new name, preserving flussenv for comparison:

conda env create -n flussenv-next -f environment.yml
conda activate flussenv-next
python -m pip install flusstools
python -m pip check
python -c "from osgeo import gdal, gdal_array; import flusstools as ft"
python -m ipykernel install --user --name fluss_kernel_next --display-name "Python (flussenv-next)"

Test the notebooks with Python (flussenv-next) before adopting the replacement. Do not run blanket pip upgrades over conda-managed packages: pip’s outdated-package list also includes distributions installed by conda.

Jupyter Book 2: Book Authoring and Migration¶

Use a separate authoring environment:

conda create -n bookenv -c conda-forge python=3.13 pip nodejs=24
conda activate bookenv
python -m pip install "jupyter-book>=2,<3"
jupyter book --version

Jupyter Book 2 uses the MyST Document Engine. To migrate a version 1 book, work on a version-controlled copy. From the directory containing _config.yml and _toc.yml, run:

jupyter book

Accept the migration prompt. The command creates myst.yml and backs up the original configuration files. Custom Sphinx extensions require MyST replacements; retain a version 1 environment until required features are available. Review migration warnings and changed page URLs, including redirects for published pages.

Build and preview the migrated book:

jupyter book build --html --strict
jupyter book start

The static site is written to _build/html. Open the preview URL printed in the terminal. Check tabs, admonitions, and cross-references before publication. See the migration guide.

Using the Environment in IDEs¶

JupyterLab¶

Activate flussenv or vflussenv, then run:

jupyter lab

Open the URL printed in the terminal and select the registered course kernel.

PyCharm¶

In Settings > Python > Interpreter > Add Interpreter > Add Local Interpreter, select the existing conda or virtual environment. Obtain its executable path from an activated terminal:

python -c "import sys; print(sys.executable)"

For the Linux venv above, the path is ~/venvs/vflussenv/bin/python. Use the printed path on Windows rather than assuming a Miniforge installation directory. See PyCharm interpreter configuration.

Deleting Environments¶

Before deleting an environment, remove its registered Jupyter kernel with jupyter kernelspec uninstall fluss_kernel (or vfluss_kernel) while Jupyter is still available. Deactivate the environment before removing it. Preserve notebooks and project files outside the environment directory.

• venv (Linux): run deactivate, then rm -rf ~/venvs/vflussenv.

• conda: run conda deactivate, then conda env remove -n flussenv.

Installation Summary¶

• Use Miniforge and the flusstools environment specification for geospatial exercises.

• Use venv for ordinary Python exercises without native GDAL requirements.

• Install conda dependencies before pip-only packages and verify imports.

• Retain tested specifications and validate updates with the course notebooks.

• Keep Jupyter Book authoring separate from the computational course environment.