How to Install rasterio in CI Without GDAL Build Failures

rasterio binds GDAL like the GDAL package does, but its modern wheels bundle GDAL - so the reliable CI path is the wheel, not a system-GDAL source build.

rasterio (1.3+) ships manylinux wheels with GDAL bundled, so a correct install just downloads a wheel and needs no system GDAL. The pain is a source build - forced by a too-new Python, musl, or pinning an old rasterio - which calls gdal-config and must match the system GDAL version.

Why it fails in CI

A rasterio source build needs libgdal-dev and gdal-config, and the rasterio version must be compatible with the installed GDAL. Slim/Alpine images have no GDAL, and a version skew between libgdal-dev and rasterio breaks the build.

gdal-config not found / Could not find gdal-config during a source build.
No matching distribution found for rasterio on a new Python/musl.
GDAL version mismatch between libgdal-dev and the rasterio source build.

Install it reliably

Keep the wheel (GDAL is bundled): glibc base, a supported Python, force-binary. Only if you must build, install libgdal-dev first and let rasterio link against it.

Terminal

# Prefer the wheel - GDAL is bundled, no system GDAL needed
pip install --only-binary=:all: rasterio

# Source build fallback (Debian/Ubuntu): system GDAL first
apt-get update && apt-get install -y libgdal-dev gdal-bin build-essential python3-dev
pip install --no-binary rasterio rasterio

Cache & speed

The wheel install is quick. If you build, libgdal-dev pulls many geospatial deps and is slow - bake GDAL into a custom image (or use a GDAL container) and cache ~/.cache/pip.

.github/workflows/ci.yml

- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: pip-rasterio-${{ hashFiles('requirements*.txt') }}

Common errors

Error	Cause	Fix
gdal-config not found	No system GDAL for source build	Use the wheel, or apt-get install libgdal-dev
No matching distribution found for rasterio	No wheel for Python/musl	Pin a supported Python; use glibc
GDAL version mismatch on build	rasterio vs libgdal skew	Use the bundled-GDAL wheel
Slow apt every job	Reinstalling GDAL each run	Bake into image / use the wheel

Key takeaways

rasterio 1.3+ wheels bundle GDAL - keep the wheel and skip system GDAL.
To build, install libgdal-dev; that reintroduces version matching.
Glibc base + a supported Python avoids the geospatial build pain.