GeoPandas: Python Guide to Install, Spatial Joins and Maps

Who this is for: researchers who already work with tables in Python and need to read, transform, join and map geographic data (boundaries, points, regions) without a desktop GIS. After reading you should be able to install GeoPandas, run a complete read, reproject, join, aggregate, plot and export workflow, and diagnose the most common mistakes. Facts below come from the official GeoPandas documentation and PyPI, read 2026-11-07.

What GeoPandas is used for in research

GeoPandas extends pandas so that a table can carry a geometry column. Its central object, the GeoDataFrame, is a subclass of pandas.DataFrame, so the filtering, grouping and merging you already use on a DataFrame (see our guide to binning values with pandas cut for one example) work on spatial data too. Typical research uses are assigning point observations (sites, clinics, samples) to administrative areas, summarising a variable by region, and producing maps for a manuscript. This is the Python route; if you work in R, the equivalent starting point is the data frame in R, and for a point-and-click alternative see how to use QGIS. For spatial omics data (a different, tissue-image problem) see SpatialData.

Install or access (official source only)

The GeoPandas installation page lists these commands:

• pip install geopandas (from PyPI)
• pip install 'geopandas[all]' (adds the optional dependencies)
• conda install geopandas or conda install --channel conda-forge geopandas

PyPI lists GeoPandas 1.2.0, released 2026-09-28, under the BSD-3-Clause licence, requiring Python 3.11 or later. After installing, the usual import is import geopandas.

Dependencies at a glance

Role	Package and minimum version (per the install page)
Required	numpy, pandas 2.2 or later, shapely 2.1 or later, pyogrio 0.8 or later, pyproj 3.7.0 or later, packaging
File reading alternative	fiona (documented as a slower alternative to pyogrio)
PostGIS databases	psycopg or psycopg2, plus GeoAlchemy2
Geocoding	geopy
Static plotting	matplotlib 3.9.0 or later, mapclassify 2.7.0 or later
Interactive maps	folium
Other optional	pointpats, scipy

The pip and conda routes both work; the install page’s own conda commands are the ones listed above. Whichever you use, keep GeoPandas in its own virtual environment so its geospatial dependencies do not conflict with other projects.

Step-by-step task: from file to map

This single path covers the steps most analyses need. The calls are the ones shown in the GeoPandas introduction and user guide; replace the file names and column names with your own.

1. Read the data. gdf = geopandas.read_file(path_to_data). The format is detected automatically.
2. Check the coordinate reference system (CRS). Inspect gdf.crs. The documentation’s New York City example is in EPSG:2263, which uses feet, so area and distance come out in square feet and feet.
3. Reproject. gdf_4326 = gdf.to_crs("EPSG:4326") converts to longitude and latitude. For measuring area or distance, use a projected CRS rather than a geographic one (see Troubleshooting).
4. Join points to polygons spatially. joined = points.sjoin(polygons, how="inner", predicate="intersects"). The documentation’s example joins grocery locations to Chicago community areas this way.
5. Aggregate by region. zones = polygons.dissolve(by="zone", aggfunc="sum") merges geometries sharing a value and summarises the other columns. The aggregation can also be a dictionary, for example "district": "count" or "population": ["min", "max"].
6. Plot. gdf.plot("area", legend=True) draws a choropleth coloured by the area column with a legend.
7. Export. gdf.to_file("my_file.geojson", driver="GeoJSON") writes the result to GeoJSON.

Output and how to read it

Spatial join predicates and the how argument

The predicate controls which spatial relationship counts as a match. The user guide lists intersects, contains, within, touches, crosses and overlaps, defined as in Shapely. The how argument controls which rows survive: left keeps the left table’s index and geometry, right keeps the right table’s, and inner keeps only rows that matched. A point on a shared boundary can satisfy intersects for two polygons, so check row counts before and after a join.

Reading a dissolve result

The dissolve output has one row per group value, with a single merged geometry and the aggregated attribute columns you requested. If you passed aggfunc="sum", every numeric column is summed, so confirm that summing makes sense for each column (a population count does; a rate does not).

Reading a plot

Passing a column name to plot colours each feature by that column. The legend is only informative if the column is in meaningful units, which depends on the CRS you chose before computing it.

Troubleshooting

Symptom	Likely cause and fix (from the documentation)
Area or distance values look wrong	The data is in a geographic CRS (degrees). The documentation warns that results in degrees may be incorrect; reproject with to_crs to a projected CRS before computing area or distance.
Plotting fails or no legend or classification options	Static plotting needs matplotlib 3.9.0 or later, and classification schemes need mapclassify 2.7.0 or later; pip install 'geopandas[all]' installs the optional set.
A join returns fewer or more rows than expected	Check how (left, right, inner) and the predicate; the predicates follow Shapely definitions, so within and contains are not interchangeable between the two tables.
Install fails on an older Python	PyPI lists Python 3.11 or later for version 1.2.0; use a newer interpreter or an environment manager.
Reading files is slow	pyogrio is the required reader; fiona is documented as the slower alternative.

Free alternatives

Tool	Environment	Use when
QGIS	Desktop GIS application	You want a graphical interface; see how to use QGIS.
sf	R package	Your analysis already lives in R.
Shapely	Python library	You only need geometry operations; GeoPandas builds on it.
DuckDB spatial extension	SQL database extension	You prefer to query spatial data with SQL.

FAQ

What is GeoPandas in Python?

An open-source library that adds geometry columns and spatial operations to pandas tables through the GeoDataFrame class, a subclass of pandas.DataFrame.

How do I install GeoPandas with pip?

Run pip install geopandas, or pip install 'geopandas[all]' to include the optional dependencies. Conda users can run conda install --channel conda-forge geopandas.

How do I import GeoPandas?

Use import geopandas, then read a file with geopandas.read_file(path).

What licence is GeoPandas under?

PyPI lists BSD-3-Clause.

Sources (official docs)

• GeoPandas: Installation (read 2026-11-07)
• GeoPandas: Introduction (read 2026-11-07)
• GeoPandas user guide: Merging data (read 2026-11-07)
• GeoPandas user guide: Aggregation with dissolve (read 2026-11-07)
• geopandas on PyPI (read 2026-11-07)