Installation Troubleshooting

Geospatial Extras and GDAL

As of the GDAL-optional-extra split, the [geo] extra installs the pure-Python geospatial stack (GeoPandas, Shapely, Fiona, PyProj, rtree, PySAL, etc.). These ship their own bundled GDAL/GEOS/PROJ inside their wheels, so pip install siege-utilities[geo] works without any system GDAL on the supported Python versions:

pip install siege-utilities[geo]

You only need system GDAL + the native OSGeo Python bindings in two cases:

You import ``osgeo`` directly (from osgeo import gdal, ogr, osr). Install the dedicated [gdal] extra, pinned to your system libgdal — the OSGeo gdal wheel must match the installed libgdal version exactly, which a bare pip install siege-utilities[geo,gdal] does not guarantee (it resolves the newest gdal in >=3.6,<4). Install system GDAL first, then pin to it — this is the path CI exercises:
```
# Ubuntu / Debian
sudo apt-get install -y gdal-bin libgdal-dev libgeos-dev libproj-dev
pip install siege-utilities[geo]
pip install "gdal==$(gdal-config --version)"
```
GeoDjango / PostGIS ([geodjango]). Django’s django.contrib.gis backend loads the system libgdal directly (via ctypes), so it needs gdal-bin libgdal-dev installed, but not the OSGeo gdal Python package:
```
sudo apt-get install -y gdal-bin libgdal-dev libgeos-dev libproj-dev
pip install siege-utilities[geodjango]
```

System Dependencies (only for the two cases above)

Ubuntu / Debian:

sudo apt-get update
sudo apt-get install -y \
    gdal-bin libgdal-dev \
    libgeos-dev libgeos++-dev \
    libproj-dev proj-bin \
    libspatialindex-dev \
    libsqlite3-mod-spatialite
pip install "gdal==$(gdal-config --version)"   # only if you need osgeo

macOS (Homebrew):

brew install gdal geos proj spatialindex
pip install "gdal==$(gdal-config --version)"   # only if you need osgeo

Windows (conda):

conda install -c conda-forge gdal geopandas
pip install siege-utilities[geo]

Choosing the Right Extras

Extra	System GDAL?	What You Get
`[geo]`	No (bundled in wheels)	GeoPandas, Shapely, Fiona, PyProj, spatial joins, choropleths, isochrones, interpolation — the full pure-Python geo stack
`[gdal]`	Yes (version-matched)	The native OSGeo `gdal` Python bindings (`from osgeo import gdal`). Add on top of `[geo]` only when you import `osgeo` directly; pin to `gdal==$(gdal-config --version)`
`[geodjango]`	Yes (libgdal at runtime)	Django ORM + DRF-GIS + PostGIS spatial queries

Common Errors

“Could not find GDAL library” (django.core.exceptions.ImproperlyConfigured)

Only relevant to GeoDjango/PostGIS. Install system GDAL (gdal-bin libgdal-dev); plain [geo] does not need it.

“OSError: cannot load library ‘libgeos_c.so’”

GEOS not installed (GeoDjango path). On Ubuntu: sudo apt install libgeos-dev.

“ModuleNotFoundError: No module named ‘osgeo’”

You imported the native OSGeo bindings without the [gdal] extra. Install system GDAL, then pip install "gdal==$(gdal-config --version)".

“Python bindings of GDAL X require at least libgdal X, but Y was found”

The OSGeo gdal wheel does not match your system libgdal. Pin it: pip install "gdal==$(gdal-config --version)". Do not rely on a bare [geo,gdal], which installs the newest compatible gdal.

DuckDB spatial “Extension … not found”

DuckDB spatial extension needs internet access on first load. Run:

import duckdb
conn = duckdb.connect()
conn.execute("INSTALL spatial; LOAD spatial")

PostGIS “relation does not exist”

Run migrations first: python manage.py migrate. Ensure PostGIS extension is enabled: CREATE EXTENSION IF NOT EXISTS postgis;