Installation#

torchgeo-bench targets Python 3.12 or newer. We recommend installing inside a fresh virtual environment using uv, which is the project’s canonical workflow.

Note

The install runs on Linux, macOS, and Windows. On Linux x86_64 it automatically includes GPU-accelerated FAISS KNN (CUDA 12, driver R525+); other platforms get CPU FAISS.

uv (recommended)#

Clone the repository and let uv create the environment and install all development dependencies:

$ git clone https://github.com/torchgeo/torchgeo-bench.git
$ cd torchgeo-bench
$ uv sync --extra dev

The install pulls in faissknn[cuda] (GPU FAISS) on Linux x86_64 and faissknn[cpu] everywhere else — no extra needed.

The torchgeo-bench console script is then available via uv run:

$ uv run torchgeo-bench --help

pip#

If you prefer pip (e.g. inside a conda environment), install the project in editable mode:

$ git clone https://github.com/torchgeo/torchgeo-bench.git
$ cd torchgeo-bench
$ pip install -e ".[dev]"

Optional extras#

A number of dependencies are gated behind PEP 621 extras so that lean benchmarking installations do not pull in heavyweight libraries by default. Combine extras with comma-separated lists:

$ uv sync --extra docs --extra viz
$ # or
$ pip install -e ".[docs,viz]"

Note

uv sync installs exactly the extras you pass and removes anything not listed, so extras do not accumulate across calls. Request them together in one command (uv sync --extra docs --extra viz) rather than running uv sync --extra docs and then uv sync --extra viz (the second drops the first).

Extra	Pulls in
`cleanlab`	`cleanlab`, `imagehash`, `matplotlib`, `pillow` (label-noise audit)
`cuda`	`faissknn[cuda]` → `faiss-cuda-cu128` for GPU KNN (Linux only; shares the `faiss` namespace with the default `faissknn[cpu]` — install in a fresh env)
`dev`	ruff, pytest, pytest-cov, pytest-xdist, pre-commit, mdformat, pyproject-fmt
`docs`	sphinx, pydata-sphinx-theme, myst-parser, sphinx-copybutton, sphinx-design
`id`	`torchid` for intrinsic-dimension metrics (Python ≥ 3.13 only)
`olmoearth`	`olmoearth-pretrain-minimal` for the OlmoEarth backbone
`sam3`	`transformers` for the SAM 3 encoder
`terratorch`	`terratorch` for TerraTorch backbones
`viz`	`matplotlib`, `pillow` for segmentation visualisations
`all`	every extra above except `cuda` (FAISS conflict) and `olmoearth`

Datasets are not installed by these extras — see Datasets for how to download GeoBench V1 / V2 with the bundled torchgeo-bench download command.