---
name: geopandas
description: Guidance and local audit tools for Python workflows that directly use GeoPandas GeoSeries, GeoDataFrame, spatial operations, or vector-data I/O.
license: MIT
compatibility: Requires Python 3.10+ and uv. Bundled CLIs are local-only; runtime analysis requires the pinned GeoPandas stack below.
allowed-tools: Read Write Bash Glob Grep
metadata:
  version: "1.1"
  skill-author: K-Dense Inc.
  last-reviewed: "2026-07-23"
---

# GeoPandas

Use GeoPandas for planar vector data represented as pandas-like `GeoSeries` and
`GeoDataFrame` objects. This skill targets stable **GeoPandas 1.1.4** (released
2026-06-26), not the unreleased 1.2 documentation.

## Reproducible environment

GeoPandas 1.1.4 requires Python 3.10+; its tagged source requires NumPy >=1.24,
pandas >=2.0, Shapely >=2.0, pyproj >=3.5, pyogrio >=0.7.2, and `packaging`.
This exact Python 3.12 snapshot was smoke-tested on 2026-07-23:

```bash
uv venv --python 3.12
uv pip install \
  "geopandas==1.1.4" \
  "numpy==2.5.1" \
  "pandas==3.0.5" \
  "shapely==2.1.2" \
  "pyproj==3.7.2" \
  "pyogrio==0.13.0" \
  "pyarrow==25.0.0" \
  "packaging==26.2"
```

Keep optional plotting and PostGIS packages pinned in the project lock as well.
Do not mix binary geospatial packages from incompatible package channels.

## Safety and privacy contract

- Treat exact coordinates, addresses, parcel boundaries, trajectories, and
  small-area joins as sensitive. Default reports to counts, categories, coarse
  extents, and redacted identifiers. Generalize before publication.
- Never automatically load a URL, cloud URI, GDAL `/vsi*` path, archive, or
  geocode an address. Obtain explicit approval, validate provenance and hashes,
  then stage an unpacked local file in an isolated workspace.
- GDAL/OGR drivers, GEOS, PROJ, pyogrio, Shapely, pyproj, and their wheels are a
  native-code trust boundary. Prefer official wheels/conda-forge, record native
  versions, restrict drivers, and process untrusted data in a sandbox.
- Do not open macro-enabled office files or nested archives through permissive
  GDAL drivers. The bundled CLIs use an extension allowlist and reject archives.
- Read only named database secrets such as `GEOPANDAS_POSTGIS_PASSWORD`; use a
  secret manager or scoped environment variable. Never embed a password in a
  URL or source, print an engine/URL, or dump the environment.
- Every derived artifact needs source hashes/versions, CRS, operation parameters,
  predicate, join cardinality, precision/repair choices, and row-count checks.

## Correctness gates

Apply these gates before trusting a result:

1. **Identity and provenance** — identify the source layer, stable feature key,
   duplicate IDs, row count, geometry column, parser/driver, and content hash.
2. **Geometry state** — count null, empty, invalid, mixed, Z/M, and collapsed
   geometries separately. `None` is missing; an empty Shapely geometry is real.
3. **CRS semantics** — require CRS metadata. `set_crs()` assigns metadata;
   `to_crs()` transforms coordinates. Never guess a CRS from coordinate ranges.
4. **Units and operation** — GeoPandas is planar. Geographic coordinates are
   angular; do not use them directly for buffer, distance, area, nearest joins,
   precision grids, or tolerances. Choose a fit-for-purpose local/equal-area CRS
   or a geodesic method.
5. **Transform quality** — inspect axis order, area of use, datum pipeline,
   expected accuracy, ballpark status, and missing grids. Keep PROJ network
   disabled unless the user explicitly approves grid retrieval.
6. **Topology and precision** — validate before and after repair/overlay. Pick a
   precision grid from source accuracy and CRS units; arbitrary snapping can
   collapse features or create bias.
7. **Cardinality** — state expected one-to-one, one-to-many, or many-to-many
   behavior before `merge`, `sjoin`, or `sjoin_nearest`; audit unmatched and
   multiplied rows afterward.
8. **Output contract** — use a new output path, preserve a stable feature ID,
   document schema/CRS/encoding, reopen the artifact, and compare counts/types.

## CRS and antimeridian rules

GeoPandas stores CRS as `pyproj.CRS`. Coordinate arrays use traditional GIS
`(x, y)` order, while authority definitions can advertise latitude-first axes.
Use `Transformer(..., always_xy=True)` for explicit coordinate-array pipelines,
and record that choice.

`to_crs()` transforms vertices and assumes each segment is straight in the
source CRS; it does not transform geodesic arcs. Geometries crossing ±180° or a
projection boundary can be badly wrapped. Detect crossings, split/unwrap and
densify in a documented geographic representation, transform parts, then
validate. Do not use Web Mercator as a general measurement CRS.

```python
crs = gdf.crs  # a pyproj.CRS when present
if crs is None or crs.is_geographic:
    raise ValueError("Choose a justified projected CRS before planar measurement")

unit_names = [axis.unit_name for axis in crs.axis_info]
areas = gdf.geometry.area  # square CRS units, not automatically square metres
```

See [CRS management](references/crs-management.md).

## Core API decisions

### Data structures

- A `GeoDataFrame` can hold multiple geometry columns, each with CRS metadata,
  but only `active_geometry_name` drives frame-level spatial operations.
- Binary `GeoSeries` methods are row-wise and align by index by default. Use
  `align=False` only when positional pairing is explicitly intended and lengths
  and order were verified.
- Duplicate column names and duplicate feature IDs are ambiguous; reject or
  resolve them before joins and exports.

See [data structures](references/data-structures.md).

### Geometry validity, precision, and union

Use `is_valid` and redacted `is_valid_reason()` categories before
`make_valid(method="linework"|"structure", keep_collapsed=...)`. Repair can
change geometry type or dimension; retain the original and compare counts,
area, types, empties, and collapsed parts.

`set_precision(grid_size, mode=...)` uses **CRS units** and may remove duplicate
vertices or collapse features. `union_all(method="unary", grid_size=...)` is the
robust default. Use `coverage` only after `is_valid_coverage()` proves
non-overlap and edge matching; use `disjoint_subset` with Shapely >=2.1 when its
partitioning assumption is useful.

See [geometric operations](references/geometric-operations.md).

### Joins, overlay, clip, and dissolve

- `sjoin` predicates are directional: `left.within(right)` is not
  `left.contains(right)`. `intersects` includes boundary contact; `contains`
  excludes boundary-only points, while `covers` includes boundary points.
- `predicate="dwithin"` requires `distance`; scalar or per-left-row distances
  are in CRS units. `sjoin_nearest` returns all equidistant nearest matches and
  does **not** implement a `k=` parameter.
- `overlay(..., make_valid=True)` repairs invalid input but can change types;
  `keep_geom_type=None` drops other types with a warning. Precision mismatch can
  create slivers; quantify them rather than silently deleting them.
- `clip` dissolves the mask. Rectangle clipping is fast but possibly dirty and
  may omit a line collapsed to a point; validate its output.
- `dissolve` combines `groupby.agg` with `union_all`; choose explicit attribute
  aggregations and audit null group keys.

See [spatial analysis](references/spatial-analysis.md).

### I/O, Arrow, and PostGIS

GeoPandas 1.x defaults to pyogrio. Driver availability and semantics come from
the installed GDAL, not GeoPandas alone. Prefer local GeoPackage for general
interchange and WKB GeoParquet for columnar interoperability.

GeoParquet defaults to stable schema 1.0.0. Native GeoArrow encodings and bbox
covering require schema 1.1.0 and remain less interoperable. A missing GeoParquet
`crs` key means `OGC:CRS84`; explicit `crs: null` means unknown—do not conflate
them. Reopen and validate every export.

Use parameterized SQL and a SQLAlchemy `Engine`/`Connection` for PostGIS.
`if_exists="replace"` is destructive; default to `"fail"` and use a transaction.

See [data I/O](references/data-io.md).

## Migration checklist

For code moving from GeoPandas 0.14 or earlier:

- GeoPandas 1.0 supports Shapely >=2 only; PyGEOS, Shapely <2, and the rtree
  spatial-index backend were removed.
- pyogrio replaced Fiona as the installed/default I/O engine. Set `engine=`
  explicitly and test schema, empty, datetime, encoding, and append behavior.
- Replace `sjoin(op=...)` with `predicate=`, `sindex.query_bulk()` with
  `sindex.query()`, `unary_union` with `union_all()`, and
  `GeometryArray.data` with `to_numpy()`/`np.asarray`.
- Replace `read_file(include_fields=...|ignore_fields=...)` with `columns=`.
  Use `schema_version=`, not the removed GeoParquet `version=` compatibility.
- Do not use removed `geopandas.datasets`, internal `geopandas.io.*` entry
  points, plot `axes`/`colormap`, or set-operation operators.
- `explode()` now defaults `index_parts=False`; a named Series passed to
  `set_geometry()` supplies the new active-column name; a named right index can
  replace `index_right` in `sjoin` output.
- Do not assign `.crs` to override metadata or rely on deprecated
  `set_geometry(drop=...)`; use explicit `set_crs()` and rename/drop steps.
- GeoPandas 1.1 requires Python >=3.10, pandas >=2.0, NumPy >=1.24, and pyproj
  >=3.5. Version 1.1.2 fixed SQL injection through a PostGIS geometry-column
  name; the pinned 1.1.4 includes that fix.

### Plotting and exploration

Maps are analytical outputs: label units, classification method, missing data,
normalization denominator, and date. `explore()` can expose every attribute in
tooltips/popups and contact tile/CDN servers; generalize first and use
`tiles=None`, `tooltip=False`, and `popup=False` for a local draft.

See [visualization](references/visualization.md).

## Bundled local CLIs

All helpers are deterministic, reject network/archive paths, bound input bytes
and feature counts, keep imports lazy so `--help` is dependency-free, and emit
JSON without coordinates or record identifiers.

| CLI | Purpose |
|---|---|
| `scripts/vector_inventory.py` | Redacted local vector/GeoParquet technical inventory |
| `scripts/crs_reprojection_plan.py` | CRS units, axes, candidate transform and antimeridian plan |
| `scripts/geometry_validity_report.py` | Dry-run validity audit; optional repair to a new GeoPackage |
| `scripts/spatial_join_audit.py` | Predicate semantics, duplicate IDs and join cardinality |
| `scripts/export_plan.py` | Non-executing vector/GeoParquet export contract |
| `scripts/sensitive_coordinates_checklist.py` | Privacy/generalization release gate |

```bash
python skills/geopandas/scripts/vector_inventory.py --help
python skills/geopandas/scripts/crs_reprojection_plan.py \
  --source-crs EPSG:4326 --target-crs EPSG:32631
python skills/geopandas/scripts/geometry_validity_report.py data.gpkg
python skills/geopandas/scripts/spatial_join_audit.py points.gpkg zones.gpkg \
  --predicate within --left-id point_id --right-id zone_id
python skills/geopandas/scripts/export_plan.py data.gpkg result.parquet \
  --format geoparquet --schema-version 1.0.0 \
  --stable-id-column feature_id --id-unique-verified
python skills/geopandas/scripts/sensitive_coordinates_checklist.py \
  --public-output --precise-points --contains-addresses
```

## Reference index

- [Data structures](references/data-structures.md)
- [CRS management](references/crs-management.md)
- [Geometric operations](references/geometric-operations.md)
- [Spatial analysis](references/spatial-analysis.md)
- [Data I/O](references/data-io.md)
- [Visualization](references/visualization.md)

## Sources (verified 2026-07-23)

- [GeoPandas 1.1.4 on PyPI](https://pypi.org/project/geopandas/1.1.4/) — released 2026-06-26.
- [GeoPandas 1.1.4 release](https://github.com/geopandas/geopandas/releases/tag/v1.1.4) — bug-fix release.
- [GeoPandas 1.1.4 tagged dependencies](https://github.com/geopandas/geopandas/blob/v1.1.4/pyproject.toml).
- [Stable GeoPandas documentation](https://geopandas.org/en/stable/).
- [GeoPandas 1.0 migration release](https://github.com/geopandas/geopandas/releases/tag/v1.0.0).