Installation Guide¶

This guide walks through setting up SWIM-RS from scratch, including dependencies and optional components.

Prerequisites¶

Python 3.13 (recommended stable version)
uv (recommended; fastest way to create a clean environment)
Git (optional; only needed for installing from source)
conda (optional; can simplify geospatial dependencies)

uv Installation (Recommended)¶

This is the quickest way to get a modern, reproducible environment with SWIM-RS.

1. Create a project and install SWIM-RS¶

If you're starting from scratch:

mkdir swim-rs && cd swim-rs
uv init --python 3.13
uv add git+https://github.com/dgketchum/swim-rs.git

If you already have a pyproject.toml, run:

uv add git+https://github.com/dgketchum/swim-rs.git

Optional extras:

uv add "swimrs[openet] @ git+https://github.com/dgketchum/swim-rs.git"

If geospatial dependencies fail to install (GDAL/PROJ issues), use the Conda Installation section below or see Install Geospatial Dependencies under Non-Conda Installation for system-library instructions.

2. Install PEST++ binaries (required for calibration)¶

SWIM-RS uses PEST++ for calibration. You can download the executables automatically via pyemu:

uv run python -c "import pyemu; pyemu.helpers.get_pestpp_binaries(dest_dir='./bin')"

3. Add `./bin` to your PATH¶

Ensure the pestpp-* executables are discoverable (so the swim CLI can find the PEST++ engine):

Linux/macOS:

export PATH="$PWD/bin:$PATH"

Windows (PowerShell):

$env:Path = "$PWD\\bin;$env:Path"

4. Verify installation¶

uv run swim --help
uv run pestpp-ies --version

Conda Installation (Alternative)¶

1. Install Conda (if needed)¶

If you don't have conda installed, we recommend Miniconda (lightweight) or Miniforge (community-driven, conda-forge default).

Option A: Miniconda¶

Download from: https://docs.conda.io/en/latest/miniconda.html

Windows: 1. Download Miniconda3-latest-Windows-x86_64.exe from the link above 2. Run the installer and follow prompts 3. Open "Anaconda Prompt" from the Start menu for conda commands

Linux:

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
bash Miniconda3-latest-Linux-x86_64.sh

macOS (Intel):

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh
bash Miniconda3-latest-MacOSX-x86_64.sh

macOS (Apple Silicon):

wget https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-arm64.sh
bash Miniconda3-latest-MacOSX-arm64.sh

Option B: Miniforge (recommended for Apple Silicon and conda-forge defaults)¶

Download from: https://github.com/conda-forge/miniforge

Windows: 1. Download Miniforge3-Windows-x86_64.exe from the releases page 2. Run the installer and follow prompts 3. Open "Miniforge Prompt" from the Start menu

Linux:

wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
bash Miniforge3-Linux-x86_64.sh

macOS (Apple Silicon):

wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-MacOSX-arm64.sh
bash Miniforge3-MacOSX-arm64.sh

After installation: - Windows: Open Anaconda Prompt or Miniforge Prompt - Linux/macOS: Restart your terminal or run source ~/.bashrc (or ~/.zshrc)

2. Create a Conda Environment¶

Create a dedicated environment for SWIM-RS. These commands work the same on Windows (Anaconda Prompt), macOS, and Linux:

conda create -n swim python=3.13 -y
conda activate swim

3. Install PEST++ (for calibration)¶

PEST++ is required for parameter estimation. Install from conda-forge:

conda install -c conda-forge pestpp -y

Verify installation:

pestpp-ies --version

You should see version output like PEST++ Version 5.x.x.

4. Install Geospatial Dependencies¶

Some geospatial libraries install more reliably via conda:

conda install -c conda-forge geopandas rasterio pyproj fiona shapely -y

5. Install SWIM-RS¶

From GitHub:

pip install git+https://github.com/dgketchum/swim-rs.git

Editable install (for development):

git clone https://github.com/dgketchum/swim-rs.git
cd swim-rs
pip install -e .

With OpenET models (optional):

To use OpenET algorithm implementations directly (for custom ETf calculations):

pip install "swimrs[openet] @ git+https://github.com/dgketchum/swim-rs.git"

Or if installing from source:

pip install -e ".[openet]"

6. Set Up Google Earth Engine (optional)¶

Earth Engine access is only needed if you want to extract fresh remote sensing data. The shipped examples include pre-extracted data.

Go to https://earthengine.google.com/ and sign up
Run earthengine authenticate and complete OAuth in browser
Verify with: python -c "import ee; ee.Initialize(); print('EE OK')"

7. Verify Installation¶

swim --help
pestpp-ies --version

Non-Conda Installation¶

If you prefer not to use conda, you can install SWIM-RS with pip and download PEST++ executables directly.

1. Create a Virtual Environment¶

Linux/macOS:

python3.13 -m venv ~/.venvs/swim
source ~/.venvs/swim/bin/activate

Windows (PowerShell):

python -m venv $env:USERPROFILE\.venvs\swim
& $env:USERPROFILE\.venvs\swim\Scripts\Activate.ps1

Windows (Command Prompt):

python -m venv %USERPROFILE%\.venvs\swim
%USERPROFILE%\.venvs\swim\Scripts\activate.bat

2. Install SWIM-RS via pip¶

pip install --upgrade pip
pip install git+https://github.com/dgketchum/swim-rs.git

Or from source:

git clone https://github.com/dgketchum/swim-rs.git
cd swim-rs
pip install -e .

3. Install PEST++ Executables¶

PEST++ is required for calibration. Recommended: download the executables automatically via pyemu:

Linux/macOS/Windows (from your activated venv):

python -c "import pyemu; pyemu.helpers.get_pestpp_binaries(dest_dir='./bin')"

Add ./bin to your PATH so swim can find the PEST++ engine:

Linux/macOS:

export PATH="$PWD/bin:$PATH"

Windows (PowerShell):

$env:Path = "$PWD\\bin;$env:Path"

Alternative: download pre-built PEST++ binaries from the official releases:

Download: https://github.com/usgs/pestpp/releases

Download the appropriate archive for your platform:
Windows: pestpp-X.X.X-win.zip
Linux: pestpp-X.X.X-linux.tar.gz
macOS: pestpp-X.X.X-mac.tar.gz
Extract and add to PATH:

Linux/macOS:

# Example for Linux
wget https://github.com/usgs/pestpp/releases/download/X.X.X/pestpp-X.X.X-linux.tar.gz
tar -xzf pestpp-X.X.X-linux.tar.gz
sudo mv pestpp-X.X.X-linux/bin/* /usr/local/bin/
# Or add to PATH in ~/.bashrc:
# export PATH="$HOME/pestpp-X.X.X-linux/bin:$PATH"

Windows: 1. Extract the zip to a folder (e.g., C:\pestpp) 2. Add to PATH: - Open System Properties → Environment Variables - Edit Path under User variables - Add C:\pestpp\bin 3. Restart your terminal

Verify:

pestpp-ies --version

4. Install Geospatial Dependencies¶

Without conda, you may need system libraries for GDAL:

Ubuntu/Debian:

sudo apt-get install gdal-bin libgdal-dev
pip install gdal==$(gdal-config --version)
pip install geopandas rasterio fiona pyproj shapely

macOS (Homebrew):

brew install gdal
pip install geopandas rasterio fiona pyproj shapely

Windows:

Use pre-built wheels from Christoph Gohlke's archive or try:

pip install pipwin
pipwin install gdal fiona rasterio
pip install geopandas pyproj shapely

Or use the OSGeo4W installer which includes GDAL and Python bindings.

5. Verify Installation¶

swim --help
pestpp-ies --version
python -c "import geopandas; print('geopandas OK')"

Complete Setup Scripts¶

uv (Linux/macOS)¶

#!/bin/bash
mkdir swim-rs && cd swim-rs
uv init --python 3.13
uv add git+https://github.com/dgketchum/swim-rs.git

# Download PEST++ binaries to ./bin
uv run python -c "import pyemu; pyemu.helpers.get_pestpp_binaries(dest_dir='./bin')"
export PATH="$PWD/bin:$PATH"

uv run swim --help && uv run pestpp-ies --version

uv (Windows — PowerShell)¶

mkdir swim-rs
cd swim-rs
uv init --python 3.13
uv add git+https://github.com/dgketchum/swim-rs.git

# Download PEST++ binaries to ./bin
uv run python -c "import pyemu; pyemu.helpers.get_pestpp_binaries(dest_dir='./bin')"
$env:Path = "$PWD\\bin;$env:Path"

uv run swim --help
uv run pestpp-ies --version

Conda (Linux/macOS)¶

#!/bin/bash
conda create -n swim python=3.13 -y && conda activate swim
conda install -c conda-forge pestpp geopandas rasterio pyproj fiona shapely -y
git clone https://github.com/dgketchum/swim-rs.git && cd swim-rs
pip install -e .
swim --help && pestpp-ies --version

Conda (Windows — Anaconda Prompt)¶

conda create -n swim python=3.13 -y && conda activate swim
conda install -c conda-forge pestpp geopandas rasterio pyproj fiona shapely -y
git clone https://github.com/dgketchum/swim-rs.git && cd swim-rs
pip install -e .
swim --help && pestpp-ies --version

Non-Conda (Linux/macOS)¶

#!/bin/bash
python3.13 -m venv ~/.venvs/swim && source ~/.venvs/swim/bin/activate
pip install --upgrade pip

# Install GDAL system library first (Ubuntu: sudo apt-get install gdal-bin libgdal-dev)
pip install geopandas rasterio fiona pyproj shapely

# Install swim-rs
git clone https://github.com/dgketchum/swim-rs.git && cd swim-rs
pip install -e .

# Download PEST++ from https://github.com/usgs/pestpp/releases and add to PATH
swim --help && pestpp-ies --version

Troubleshooting¶

GDAL/Fiona errors¶

If you see GDAL-related errors, ensure geospatial libs are from conda:

conda install -c conda-forge gdal fiona rasterio --force-reinstall -y

PEST++ not found¶

If you're using uv (recommended), download the binaries and ensure ./bin is on your PATH:

uv run python -c "import pyemu; pyemu.helpers.get_pestpp_binaries(dest_dir='./bin')"
export PATH="$PWD/bin:$PATH"

If you're using conda, install via conda-forge:

conda install -c conda-forge pestpp -y

Earth Engine authentication fails¶

Try re-authenticating with a fresh token:

earthengine authenticate --force

Import errors after pip install¶

Ensure you're in the correct conda environment:

conda activate swim
which python  # Linux/macOS - should point to your conda env
where python  # Windows - should point to your conda env

Apple Silicon (M1/M2) issues¶

Use Miniforge instead of Miniconda for better ARM64 support:

conda install -c conda-forge numpy scipy pandas --force-reinstall -y

Windows: "swim" command not found¶

If you installed with uv, run commands via:

uv run swim --help

If you installed with conda, ensure you're in the Anaconda/Miniforge Prompt (not regular Command Prompt or PowerShell). Alternatively, use:

python -m swimrs.cli --help

Windows: Long path errors¶

Enable long paths in Windows 10/11: 1. Open Group Policy Editor (gpedit.msc) 2. Navigate to: Computer Configuration → Administrative Templates → System → Filesystem 3. Enable "Enable Win32 long paths"

Or via Registry:

reg add "HKLM\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f

Windows: Git not found¶

Install Git for Windows from: https://git-scm.com/download/win

Or install via conda:

conda install -c conda-forge git -y

Environment File (optional)¶

For reproducible environments, create environment.yml:

name: swim
channels:
  - conda-forge
  - defaults
dependencies:
  - python=3.13
  - pestpp
  - geopandas
  - rasterio
  - pyproj
  - fiona
  - shapely
  - numpy
  - scipy
  - pandas
  - xarray
  - zarr
  - pip
  - pip:
    - git+https://github.com/dgketchum/swim-rs.git

Install with:

conda env create -f environment.yml
conda activate swim

Next Steps¶

Run the Quick Start example
Explore the Examples for tutorials and workflows
Read the Data Extraction Guide if you need to pull fresh EE data

Installation Guide¶

Prerequisites¶

uv Installation (Recommended)¶

1. Create a project and install SWIM-RS¶

2. Install PEST++ binaries (required for calibration)¶

3. Add ./bin to your PATH¶

4. Verify installation¶

Conda Installation (Alternative)¶

1. Install Conda (if needed)¶

Option A: Miniconda¶

Option B: Miniforge (recommended for Apple Silicon and conda-forge defaults)¶

2. Create a Conda Environment¶

3. Install PEST++ (for calibration)¶

4. Install Geospatial Dependencies¶

5. Install SWIM-RS¶

6. Set Up Google Earth Engine (optional)¶

7. Verify Installation¶

Non-Conda Installation¶

1. Create a Virtual Environment¶

2. Install SWIM-RS via pip¶

3. Install PEST++ Executables¶

4. Install Geospatial Dependencies¶

5. Verify Installation¶

Complete Setup Scripts¶

uv (Linux/macOS)¶

uv (Windows — PowerShell)¶

Conda (Linux/macOS)¶

Conda (Windows — Anaconda Prompt)¶

Non-Conda (Linux/macOS)¶

Troubleshooting¶

GDAL/Fiona errors¶

PEST++ not found¶

Earth Engine authentication fails¶

Import errors after pip install¶

Apple Silicon (M1/M2) issues¶

Windows: "swim" command not found¶

Windows: Long path errors¶

Windows: Git not found¶

Environment File (optional)¶

Next Steps¶

3. Add `./bin` to your PATH¶