How to Install Cartopy in CI Without GEOS/PROJ Build Failures

Cartopy depends on Shapely, GEOS, and PROJ. Modern wheels ease installs, but a source build needs the GEOS and PROJ dev libraries that slim runners lack.

Cartopy is a mapping library built on GEOS and PROJ (via Shapely and pyproj). It ships wheels for common platforms, but a source build - triggered by a too-new Python or musl - needs libgeos-dev, libproj-dev, and the PROJ data files, which CI images rarely have.

Why it fails in CI

A Cartopy source build needs the GEOS and PROJ development libraries plus PROJ data. Slim and Alpine images have none of that, so the build fails looking for proj.h/geos_c.h. At runtime, a missing PROJ data directory breaks projections.

• Proj 8.0.0 must be installed / fatal error: proj.h: No such file or directory.
• fatal error: geos_c.h: No such file or directory during the build.
• No matching distribution found for Cartopy on a new Python/musl.

Install it reliably

Prefer the wheel (its deps bundle GEOS/PROJ): glibc base, a supported Python, force-binary. If you must build, install the GEOS and PROJ dev packages and PROJ data.

# Prefer the wheel (pyproj/shapely wheels bundle PROJ/GEOS)
pip install --only-binary=:all: cartopy

# Source build fallback (Debian/Ubuntu)
apt-get update && apt-get install -y \
  libgeos-dev libproj-dev proj-data proj-bin build-essential python3-dev
pip install cartopy

Cache & speed

The wheel install is quick. If you build, the GEOS/PROJ install is slow - bake those dev packages into a custom image and cache ~/.cache/pip.

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

Common errors

Key takeaways

• Cartopy builds on GEOS + PROJ - keep it (and pyproj/shapely) on wheels.
• To build, install libgeos-dev + libproj-dev + proj-data.
• Glibc base + a supported Python avoids the geospatial build.

Related guides