How to Install Shapely in CI Without GEOS Errors

Modern Shapely wheels bundle GEOS, so installs are clean - the pain is a source build hunting for libgeos-dev, or a clash with a system GEOS.

Shapely (2.x) ships manylinux wheels with GEOS bundled, so a correct install needs nothing extra. CI breaks when a too-new Python or musl forces a source build that searches for geos-config/libgeos-dev, or when a mismatched system GEOS conflicts with the bundled one.

Why it fails in CI

A Shapely source build needs the GEOS development library and geos-config. Slim and Alpine images lack them, so the build fails. Conversely, an old Shapely linking a too-old system GEOS raises a runtime version error.

• Could not find geos-config / GEOS library not found during a source build.
• No matching distribution found for shapely on a new Python/musl.
• Runtime GEOS version mismatch when linking an old system GEOS.

Install it reliably

Keep the wheel (GEOS is bundled): glibc base, a supported Python, and force-binary. Only install libgeos-dev if you deliberately build from source.

# Prefer the wheel - GEOS is bundled, nothing to install
pip install --only-binary=:all: shapely

# Source build fallback (Debian/Ubuntu)
apt-get update && apt-get install -y libgeos-dev build-essential python3-dev
pip install --no-binary shapely shapely

Cache & speed

The wheel install is instant. If you build, bake libgeos-dev into the image and cache ~/.cache/pip so a successful build is reused.

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

Common errors

Key takeaways

• Shapely 2.x wheels bundle GEOS - keep the wheel and no system lib is needed.
• To build, install libgeos-dev; do it only deliberately.
• Glibc base + a supported Python avoids the GEOS-header dance.

Related guides