GeoPandas Installation Fails: How to Fix Common Errors

Problem statement

GeoPandas installation errors usually happen because GeoPandas depends on compiled spatial libraries, not just pure Python code. GeoPandas itself is pure Python; the packages under it — Shapely (geometry, on the GEOS library), pyproj (coordinate systems, on PROJ) and pyogrio (file reading, on GDAL) — wrap native C and C++ libraries, and that is where installs fail.

Until those three agree, nothing else on this site runs. The failures fall into four groups:

• pip install geopandas fails, or installs an older version than you expected
• a package such as Fiona fails to build with a gdal-config error
• a conda environment ends up mixing channels
• GeoPandas installs but import geopandas (or a check that imports Fiona) fails afterward

Every error message on this page was reproduced on 30 September 2026 in clean python:3.10-slim and python:3.14-slim Docker containers and in fresh conda environments, so they are the messages current releases actually print.

Quick answer

The safest way to avoid GeoPandas installation errors is to install the whole stack in one step into a new environment, from one source.

With conda, take everything from conda-forge in a single command:

conda create -n gis -c conda-forge --override-channels python=3.12 geopandas -y
conda activate gis

With pip, use a fresh virtual environment on a supported Python:

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install geopandas

On Python 3.14 in a clean container, that pip install needed no compiler: it pulled prebuilt wheels for GeoPandas 1.2.0, Shapely 2.1.2, pyproj 3.8.0 and pyogrio 0.13.0, which carry their own GEOS 3.13.1, PROJ 9.8.1 and GDAL 3.12.4. The conda-forge command took 29 seconds and installed 156 packages, all from conda-forge.

Most install problems come from:

• a package with no wheel for your Python version, so pip tries to compile it
• a Python version the newest release no longer supports
• mixing package sources (pip and conda, or conda's defaults and conda-forge) in one environment
• running code with a different interpreter from the one you installed into

Read the real error, then fix pip, conda or imports

Step 1: Identify the exact installation error

Do not focus only on the last line of output. Pip's last lines are generic (note: This error originates from a subprocess, and is likely not a problem with pip.); the first ERROR, WARNING or CRITICAL line names the real cause.

The four you are most likely to meet:

• Failed to get options via gdal-config — pip found no wheel and is compiling a GDAL binding from source
• Ignored the following versions that require a different python version followed by No matching distribution found — the release you asked for does not support your Python
• ModuleNotFoundError: No module named 'fiona' after a successful install — expected with GeoPandas 1.0 and later
• ModuleNotFoundError: No module named 'geopandas' after a successful install — the code runs in a different interpreter

Step 2: Check Python version and environment

First confirm which Python and pip you are actually using.

python --version
python -c "import sys; print(sys.executable)"
python -m pip --version

If the Python path and the path in pip --version point to different places, installation goes to one environment while your code runs from another. Using python -m pip rather than a bare pip removes that gap, because it is always the pip of the Python you named.

The Python version matters because GeoPandas and its dependencies drop old versions. GeoPandas 1.2.0 requires Python 3.11 or later and pyproj 3.8.0 requires 3.12. On Python 3.10, asking for the current release fails:

$ python --version
Python 3.10.21
$ python -m pip install "geopandas==1.2.0"
ERROR: Ignored the following versions that require a different python version: 1.2.0 Requires-Python >=3.11
ERROR: Could not find a version that satisfies the requirement geopandas==1.2.0 (from versions: ..., 1.1.3, 1.1.4)
ERROR: No matching distribution found for geopandas==1.2.0

and an unpinned pip install geopandas on the same Python quietly succeeds with the newest versions that still support it — GeoPandas 1.1.4 and pyproj 3.7.1. That is not an error, but it is why two machines can end up with different versions from the same command.

Step 3: Fix pip-based installation errors

If pip starts compiling something, it has found no wheel for your platform and Python. The commonest case today is Fiona, which GeoPandas no longer needs but older instructions still install. Fiona 1.10.1 publishes wheels up to Python 3.13, so on Python 3.14:

$ python -m pip install fiona
Collecting fiona
  Downloading fiona-1.10.1.tar.gz (444 kB)
  ...
  × Getting requirements to build wheel did not run successfully.
  │ exit code: 1
  ╰─> [2 lines of output]
      WARNING:root:Failed to get options via gdal-config: [Errno 2] No such file or directory: 'gdal-config'
      CRITICAL:root:A GDAL API version must be specified. Provide a path to gdal-config using a GDAL_CONFIG environment variable or use a GDAL_VERSION environment variable.
      [end of output]
ERROR: Failed to build 'fiona' when getting requirements to build wheel

fiona-1.10.1.tar.gz is the tell: pip downloaded source code, not a wheel. The fixes, in order of preference:

1. Don't install it. If nothing in your code imports fiona, remove it from your requirements; GeoPandas reads and writes files with pyogrio.
2. Use a Python version that has wheels — Python 3.13 or earlier for Fiona 1.10.1.
3. Refuse source builds so the failure is immediate and clear: python -m pip install --only-binary=:all: fiona fails on Python 3.14 with No matching distribution found for fiona instead of starting a build.
4. Install GDAL's development files (gdal-config comes with them) only if you really need to compile against a system GDAL.

Pip works well when your Python version is supported, wheels exist for your platform, and you are in an isolated environment. It fails when it has to build native GIS code, or when an environment already holds conflicting packages.

Step 4: Fix conda-based installation errors

Install from conda-forge in a new environment, and name the channel in the same command that installs Python. A common recipe does it in two steps:

conda create -n gis python=3.11 -y
conda install -n gis -c conda-forge geopandas -y

With Miniconda's default configuration, the first command takes Python from Anaconda's defaults channel. Run on this machine, the second command then installed GeoPandas 1.2.0 from conda-forge but kept 45 of the environment's 150 packages from defaults, including Python, Shapely and the GDAL library. That environment did import and reproject, but it is exactly the mix of builds that later produces solver conflicts and library errors. The one-step command in the quick answer, with --override-channels, gave 156 packages all from conda-forge.

If conda reports solver conflicts:

• create a new environment instead of reusing an old one
• use one channel, conda-forge, for the whole stack
• install GeoPandas and everything else you need in one command, rather than one package at a time

Step 5: Fix dependency-specific errors

GeoPandas depends on several libraries:

• Shapely: geometry operations, on GEOS
• pyproj: coordinate reference systems and reprojection, on PROJ
• pyogrio: file reading and writing, on GDAL (the default engine since GeoPandas 1.0)
• Fiona: the older file engine, now optional — installed only if you ask for it

A single failure can block the full install:

• Shapely or pyproj trying to build means there is no wheel for your Python or platform: change the Python version or use conda-forge.
• Fiona or a GDAL binding trying to build fails without gdal-config, as in Step 3.
• PROJ errors at runtime, such as a missing proj.db, usually mean a leftover PROJ_LIB or PROJ_DATA variable, or libraries from two sources, pointing PROJ at the wrong data.

If one dependency fails under pip, the practical fix is often to stop patching the environment and install the full stack in a clean one.

Step 6: Fix import errors after installation

Sometimes installation succeeds, but this fails:

import geopandas as gpd

In a Python where GeoPandas was never installed, the message is ModuleNotFoundError: No module named 'geopandas' — the usual cause is an editor, notebook kernel or scheduled job using a different interpreter from the terminal where you ran pip. Check which interpreter is running:

python -c "import sys; print(sys.executable)"

A check that imports Fiona fails on a perfectly good modern install. After pip install geopandas on Python 3.14:

$ python -c "import geopandas, shapely, fiona, pyproj; print('ok')"
ModuleNotFoundError: No module named 'fiona'

Leave fiona out of the check (Step 7), or install it deliberately if your own code uses it.

Since GeoPandas 1.0 Fiona is optional: GeoPandas requires pyogrio and reads and writes with it by default. An error that names Fiona therefore comes from one of three places — GeoPandas older than 1.0, code that passes engine="fiona", or another package that imports Fiona itself. In a fresh install, engine="fiona" raises an ImportError that says so (the example A fresh install, with and without Fiona below). Drop the argument, or pip install fiona into the same environment; the two engines then read the same file, each with its own bundled GDAL.

Other causes of import errors after installation are Windows DLL errors from a binary built for a different environment, and pip and conda packages mixed in one environment. In those cases rebuilding the environment is usually faster than repairing it.

Step 7: Test that GeoPandas is installed correctly

Print the versions of the stack and of the native libraries it loaded:

import geopandas
import pyogrio
import pyproj
import shapely

print("geopandas", geopandas.__version__, "| shapely", shapely.__version__,
      "| pyproj", pyproj.__version__, "| pyogrio", pyogrio.__version__)
print("GEOS", shapely.geos_version_string, "| PROJ", pyproj.proj_version_str,
      "| GDAL", pyogrio.__gdal_version_string__)

geopandas 1.1.4 | shapely 2.1.2 | pyproj 3.8.0 | pyogrio 0.13.0
GEOS 3.13.1 | PROJ 9.8.1 | GDAL 3.12.4

(These are the versions in the environment this page's code was run in; a fresh install today may be newer.)

Then run a minimal GIS test that exercises all three native libraries — geometry, reprojection and a file round trip:

import os
import tempfile

import geopandas as gpd
from shapely.geometry import Point

gdf = gpd.GeoDataFrame(
    {"city": ["London", "Paris"]},
    geometry=[Point(-0.1276, 51.5072), Point(2.3522, 48.8566)],
    crs="EPSG:4326",
)
print(gdf.to_crs("EPSG:3857"))

path = os.path.join(tempfile.mkdtemp(), "check.gpkg")
gdf.to_file(path)
print(gpd.read_file(path).crs, len(gpd.read_file(path)), "rows read back")

     city                        geometry
0  London  POINT (-14204.367 6711506.705)
1   Paris   POINT (261845.706 6250564.35)
EPSG:4326 2 rows read back

This confirms:

• GeoPandas imports correctly
• Shapely works for geometry creation
• pyproj can find its database and transform coordinates
• pyogrio (GDAL) can write and read a GeoPackage

Clean environments, wheel-only installs and version reports

The data used on this page

One known-good file to test reading with: Natural Earth's populated places at 1:110 million, as GeoJSON. The other examples on this page are shell commands.

import os

import geopandas as gpd

os.makedirs("data", exist_ok=True)
if not os.path.exists("data/cities.geojson"):
    gpd.read_file("https://naciscdn.org/naturalearth/110m/cultural/ne_110m_populated_places.zip"
                  )[["NAME", "ADM0NAME", "POP_MAX", "geometry"]].to_file("data/cities.geojson")
print(len(gpd.read_file("data/cities.geojson")), "cities")

243 cities

A fresh install, with and without Fiona

This builds a fresh virtual environment, installs GeoPandas the way a new user would, and asks what it depends on, which engine it reads with, and what happens when code asks for Fiona:

import subprocess
import venv

venv.create("fresh-env", with_pip=True)
python = os.path.join("fresh-env", "bin", "python")
pip = lambda *packages: subprocess.run([python, "-m", "pip", "install", "-q", *packages],
                                       check=True, capture_output=True)
CHECK = """
import importlib.util, geopandas as gpd, pyogrio
print("geopandas", gpd.__version__, "| fiona installed:", importlib.util.find_spec("fiona") is not None,
      "| io_engine:", gpd.options.io_engine)
print("default engine reads", len(gpd.read_file("data/cities.geojson")), "features")
try:
    gpd.read_file("data/cities.geojson", engine="fiona")
    import fiona
    print("engine='fiona' reads it too; GDAL in fiona", fiona.__gdal_version__,
          "| in pyogrio", pyogrio.__gdal_version_string__)
except ImportError as error:
    print(type(error).__name__ + ":", str(error).replace("\\n", " / "))
"""
pip("geopandas")
print(subprocess.run([python, "-m", "pip", "show", "geopandas"], capture_output=True, text=True)
      .stdout.splitlines()[-2])
print(subprocess.run([python, "-c", CHECK], capture_output=True, text=True).stdout)
pip("fiona")
print(subprocess.run([python, "-c", CHECK], capture_output=True, text=True).stdout)

Requires: numpy, packaging, pandas, pyogrio, pyproj, shapely
geopandas 1.2.0 | fiona installed: False | io_engine: None
default engine reads 243 features
ImportError: the 'read_file' function requires the 'fiona' package, but it is not installed or does not import correctly. / Importing fiona resulted in: No module named 'fiona'

geopandas 1.2.0 | fiona installed: True | io_engine: None
default engine reads 243 features
engine='fiona' reads it too; GDAL in fiona 3.12.2 | in pyogrio 3.12.4

Check active Python executable and pip path

python -c "import sys; print(sys.executable)"
python -m pip --version

Create and activate a clean virtual environment

python -m venv .venv

Windows

.venv\Scripts\activate

macOS / Linux

source .venv/bin/activate

Install GeoPandas with pip, wheels only

python -m pip install --upgrade pip
python -m pip install --only-binary=:all: geopandas

--only-binary=:all: makes pip fail at once with No matching distribution found rather than attempting to compile, which is the error you want when a wheel is missing.

Create a conda environment from conda-forge only

conda create -n gis -c conda-forge --override-channels python=3.12 geopandas -y
conda activate gis
conda list | grep -v conda-forge   # anything listed here came from another channel

Print installed versions

python -c "import geopandas, shapely, pyproj, pyogrio; print(geopandas.__version__, shapely.__version__, pyproj.__version__, pyogrio.__version__)"

Print GeoPandas' own report

import geopandas
geopandas.show_versions()

show_versions() lists the Python, the native library versions and their paths, and the optional dependencies — the report to paste into a bug report.

Why GeoPandas depends on compiled libraries

GeoPandas installation can be more complex than installing a pure Python package because parts of the GIS stack depend on compiled binary libraries. These libraries handle geometry operations, projections, and spatial file formats such as shapefiles and GeoJSON.

That is why a dependency error often appears even when GeoPandas itself is not the direct problem.

Wheels changed the picture. Shapely, pyproj and pyogrio now ship wheels with GEOS, PROJ and GDAL built in, so on a supported Python a plain pip install geopandas compiles nothing. The failures that remain are the edges: a Python release newer than a package's wheels (Fiona on 3.14), older than a package's support (GeoPandas 1.2 on 3.10), or an environment in which two sources have installed different builds of the same libraries.

A clean environment helps because it removes old package conflicts. Conda-forge works well for GIS stacks because it builds GDAL, PROJ and GEOS once and links every package against the same copies; pip wheels each carry their own copy, which is fine as long as nothing else in the environment loads a different one.

Windows DLLs, macOS, Linux and mixed package managers

Windows-specific issues

• DLL load failed usually means a binary dependency is missing or was built for a different environment
• Visual C++ build errors appear when pip tries to compile from source — the same missing-wheel situation as the gdal-config error on Linux
• make sure Python is 64-bit: pyogrio 0.13.0 publishes Windows wheels only for 64-bit x86 (win_amd64), so on 32-bit or ARM Windows pip tries to compile it

macOS-specific issues

• Apple Silicon and Intel builds are different; an Intel Python under Rosetta installs Intel wheels
• Homebrew GIS libraries can be picked up by source builds and conflict with the libraries inside wheels

Linux-specific issues

• errors mentioning gdal-config mean pip is compiling and GDAL's development files are missing
• distro packages (python3-gdal, python3-shapely) and pip-installed packages can conflict in the same interpreter; keep pip installs in a virtual environment

Avoid mixing package managers

Do not install some GIS dependencies with conda and others with pip in the same environment unless you have a specific reason and understand the consequences. The same goes for conda channels: defaults and conda-forge build GDAL and PROJ separately. If you already mixed them and now have a broken environment, recreate it.

GIS note on CRS and geometry tests

After install, do a real GIS check like the one in Step 7: create a GeoDataFrame with a known CRS, reproject it and write a file. An import that succeeds proves little; a reprojection proves PROJ found its database, and a file round trip proves GDAL works.

Internal links

If you need more background, read How Python Environments Work for GIS Projects.

For related GIS troubleshooting, see How to Fix CRS Mismatch in GeoPandas and GeoPandas Not Reading Shapefile: Common Causes and Fixes.

If GeoPandas is installed but still performs poorly on real data, see How to Speed Up GeoPandas: Tips for Large Datasets.

FAQ

Why does pip install geopandas fail on Windows?

Usually because pip is trying to build a compiled dependency and the required binary tools or compatible wheels are not available. A fresh conda-forge environment is often the fastest fix.

Should I use pip or conda to install GeoPandas?

If you already use conda, use conda-forge first. For GIS stacks, it is usually more reliable. Pip is fine in a clean virtual environment when compatible wheels are available.

Why does GeoPandas install successfully but fail to import?

The most common reasons are using the wrong environment, mixing pip and conda packages, or a broken dependency. A check that imports fiona also fails on a correct install of GeoPandas 1.0 or later, because Fiona is no longer installed with it.

How do I know which dependency caused the GeoPandas installation error?

Read the first meaningful error in the install log. If the message mentions Fiona, GDAL, pyproj, or Shapely, that dependency is usually the actual source of the failure; a .tar.gz being downloaded means pip is about to compile it.

Which Python versions does GeoPandas support?

GeoPandas 1.2.0 requires Python 3.11 or later, and pyproj 3.8.0 requires 3.12. At the other end, a new Python can arrive before every package has wheels: on Python 3.14 the core stack installed from wheels, but Fiona 1.10.1 did not. python=3.12 or 3.13 is a safe choice.

Do I need Fiona to use GeoPandas?

No, not since GeoPandas 1.0: it reads and writes with pyogrio, and a fresh pip install geopandas does not install Fiona. You need Fiona only for code that passes engine="fiona" or imports it directly.

Do I still need to install GDAL separately for GeoPandas?

In a conda-forge environment GDAL is pulled in automatically as a dependency, so you do not install it by hand. With modern pip wheels, Shapely, pyproj and pyogrio bundle the native libraries they need, so a manual GDAL install is only relevant when pip is forced to build from source.

How do I install a specific GeoPandas version with pip?

Pin the version directly, for example pip install "geopandas==1.1.4", ideally inside a fresh virtual environment. Pinning helps reproduce an older working setup or avoid a release that lacks wheels for your platform.

Why do I get a PROJ or proj.db error after installing GeoPandas?

This usually means PyProj cannot find its PROJ data files, often because pip and conda packages were mixed or an external PROJ_LIB or PROJ_DATA environment variable points at the wrong location. Unset any such variable you set by hand, and if that does not help, rebuild the stack in one clean environment.