Installing GeoWombat

Prerequisites

GeoWombat requires Python 3.10, 3.11, or 3.12.

The recommended installation method is Conda, which handles the core dependencies (including GDAL/rasterio) automatically on every platform. Optional extras are available as separate Conda sub-packages (see Optional extras below). If you prefer pip, see the sections below.

Install with Conda (recommended)

Conda provides the easiest and most consistent installation across Linux, macOS, and Windows. See the Conda installation instructions for setup.

Add the conda-forge channel and install:

conda config --add channels conda-forge
conda config --set channel_priority strict
conda install geowombat

Or with mamba for faster dependency resolution:

mamba install geowombat

Alternatively, install in one line following the GeoWombat Conda page:

conda install -c conda-forge geowombat

Install with pip

GeoWombat can be installed from the GitHub repository using pip. Because GeoWombat includes Cython extensions that must be compiled, a C compiler is required (gcc on Linux, Xcode command-line tools on macOS, or Visual Studio Build Tools on Windows).

Linux / macOSWindows

Install GeoWombat from GitHub:

pip install git+https://github.com/jgrss/geowombat

To install a specific version (e.g., v2.1.22):

pip install git+https://github.com/jgrss/geowombat@v2.1.22

To include optional extras (e.g., ml and stac):

pip install "geowombat[ml,stac]@git+https://github.com/jgrss/geowombat.git"

GDAL system libraries

Most users do not need to install GDAL separately. GeoWombat depends on rasterio<1.5.0, which ships with its own bundled GDAL libraries on all platforms. The bundled GDAL is sufficient for reading and writing GeoTIFFs, reprojection, warping, and all standard GeoWombat operations.

However, a system GDAL installation may be needed if you:

• Want to use GDAL command-line tools (gdalinfo, gdal_translate, etc.) outside of Python

• Need drivers not included in the rasterio wheel (e.g., certain HDF or database-backed formats)

• Are building rasterio or GDAL Python bindings from source

macOSWindowsLinux

Install GDAL via Homebrew:

brew install gdal

Verify the installation:

gdalinfo --version

Development install

For contributors who want an editable install:

Warning

Editable installs require --no-build-isolation. Meson-python caches the NumPy include path at configure time. With build isolation, this path points to a temporary directory that is deleted after install, causing import geowombat to fail on the next rebuild. Using --no-build-isolation ensures paths point to your actual environment.

Setup and installRebuild after changesCode formatting

Clone and install in editable mode:

git clone https://github.com/jgrss/geowombat.git
cd geowombat/
pip install --no-build-isolation -e ".[tests]"

To include additional extras for development (e.g., ML and docs):

pip install --no-build-isolation -e ".[ml,tests,docs]"

Optional extras

GeoWombat provides optional dependency groups for specific functionality.

Extra	Description
ml	Machine learning and classification (dask-ml, lightgbm, sklearn-xarray, numba)
dl	Deep learning (PyTorch, pytorch-tabnet, torchgeo, segmentation-models-pytorch)
stac	STAC catalog data access (pystac, stackstac, planetary-computer)
coreg	Sub-pixel co-registration (arosics and dependencies)
perf	Performance: rtree, pygeos, netCDF4, ray
time	Automatic date parsing (dateparser)
view	Map visualization (bokeh, descartes, graphviz)
web	Web data access (gsutil, wget)
zarr	Zarr format support (zarr, numcodecs)
docs	Sphinx documentation building
tests	Testing dependencies (testfixtures, pre-commit, etc.)

Installing extras with pip

Append [extra_name] to your pip install command. Multiple extras can be combined:

pip install "geowombat[ml,stac]@git+https://github.com/jgrss/geowombat.git"

Installing extras with Conda

With Conda, optional extras are installed as separate sub-packages — they are not included by a plain conda install geowombat. Install them by name, e.g.:

conda install geowombat-ml geowombat-stac

The available Conda sub-packages are: geowombat-ml, geowombat-stac, geowombat-coreg, geowombat-perf, geowombat-view, geowombat-web, geowombat-zarr, geowombat-docs, and geowombat-tests.

See the conda-forge feedstock for the full recipe.

Note

Conda differences from pip extras:

• time (dateparser) is included in the base Conda package automatically; with pip it is an optional extra.

• dl (deep learning) is not available as a Conda sub-package. Install deep learning dependencies with pip:

  pip install torch pytorch-tabnet torchgeo segmentation-models-pytorch
  

• A few packages are unavailable on conda-forge and are omitted from the Conda sub-packages: wrapt-timeout-decorator (stac), sphinx_tabs (docs), and pygeos (perf; deprecated — its functionality is now in shapely 2.0+).

Test the installation

Verify the import

If GeoWombat installed correctly, the following should print the version:

python -c "import geowombat as gw; print(gw.__version__)"

Run the test suite

Install test dependencies if not already installed:

pip install testfixtures

Run all tests from the tests/ directory:

cd geowombat/tests/
python -m unittest discover -p 'test_*.py'

Run a single test file:

cd geowombat/tests/
python -m unittest test_open

Run a single test method:

cd geowombat/tests/
python -m unittest test_open.TestOpen.test_open

Troubleshooting

Note

Build fails with NumPy errors

If you see errors mentioning PyArray_Descr has no member named 'subarray' or numpy/_core/include not found, your build environment may have NumPy 2.x despite the numpy<2 pin in pyproject.toml. This can happen with older pip versions or cached build artifacts. Try upgrading pip and clearing the build cache:

pip install --upgrade pip
pip install --no-cache-dir git+https://github.com/jgrss/geowombat

If the problem persists, install numpy<2 explicitly and bypass build isolation:

pip install "numpy<2"
C_INCLUDE_PATH=$(python -c "import numpy; print(numpy.get_include())") \
  pip install --no-build-isolation git+https://github.com/jgrss/geowombat

Note

Editable install fails with re-building the geowombat meson-python editable wheel package failed

This means the meson build cache has stale paths (usually from a previous build isolation environment). Delete the build directory and reinstall:

rm -rf build/
pip install --no-build-isolation -e ".[tests]"

Note

setuptools_scm version error

If the build fails with Command 'from setuptools_scm import get_version' failed, install setuptools_scm in your environment:

pip install setuptools_scm

Note

OpenMP not found (macOS)

The Cython moving-window extensions optionally use OpenMP for parallelism. On macOS, you may need to install libomp via Homebrew:

brew install libomp

The build will succeed without OpenMP, but moving-window operations will run single-threaded.