geopeek

A fast, friendly CLI for inspecting geospatial files — CRS, extent, schema, and health checks in one command.

geopeek is a single-command inspector for the geospatial files you deal with every day — shapefiles, GeoJSON, GeoPackage, GeoParquet, GeoTIFF, and friends. It tells you the CRS, the extent, the schema, a sample of features, and — most importantly — what's wrong with the file before you build a pipeline around it.

Maintained by python-geospatial.com, a knowledge base for processing, analysing, and visualising location data with the modern Python geospatial stack.

Why?

Half the time spent on a geospatial task is figuring out what's actually in the file someone sent you. ogrinfo and gdalinfo answer the what; geopeek also answers the should I be worried?:

• Is the CRS missing or suspicious?
• Are there invalid or empty geometries?
• Are geometry types mixed?
• Do features carry Z coordinates that downstream code will silently drop?
• Does the raster lack a nodata value, or is its transform identity?

One command, one screen, no surprises.

Install

pip install git+https://github.com/python-geospatial/geopeek.git

Requires Python 3.10+. Pulls in geopandas, rasterio, shapely, pyproj, click, and rich.

Usage

geopeek path/to/file.shp
geopeek dem.tif
geopeek parcels.gpkg --json          # machine-readable summary
geopeek roads.geojson --sample 10    # show 10 sample features
geopeek dem.tif --no-sample          # rasters never sample anyway

The CLI exits with status 1 when warnings are emitted — handy in CI pipelines that vet incoming data.

Vector example

╭────────────────────────────────────────────────╮
│ roads.geojson                                  │
│ vector · GeoJSON · 1284 features               │
╰────────────────────────────────────────────────╯
  CRS          WGS 84  ·  EPSG:4326  ·  degree
  Geometry     LineString × 1284
  Bounds       (4.123456, 50.987654) → (5.123456, 51.987654)
  Geom column  geometry

  ┌─ Warnings ────────────────────────────────────────────────┐
  │ • 3 invalid geometry value(s) — run `make_valid` before   │
  │   spatial ops.                                            │
  │ • Z (3D) coordinates present — some libraries silently    │
  │   drop them.                                              │
  └───────────────────────────────────────────────────────────┘

Raster example

╭─────────────────────────────────────────╮
│ dem.tif                                 │
│ raster · GTiff · 4096×4096 · 1 band(s)  │
╰─────────────────────────────────────────╯
  CRS         EPSG:3857
  Bounds      (-20037508, -20037508) → (20037508, 20037508)
  Pixel size  10 × 10
  Dtypes      float32
  Nodata      -9999.0

  No issues detected.

JSON mode

geopeek roads.geojson --json | jq '.crs.epsg, .warnings'

Every field shown in the human view is present in the JSON payload — feed it straight into a data-quality dashboard or a pre-commit hook.

Supported formats

Kind	Extensions
Vector	.shp .geojson .json .gpkg .kml .gml .fgb .gpx .parquet
Raster	.tif .tiff .jp2 .png .img .vrt .asc .nc .hdf .grib

Anything readable by GDAL through rasterio / fiona should work; the table above lists what's auto-detected by extension.

Learn more

Each warning in geopeek corresponds to a real workflow on the python-geospatial.com knowledge base:

• Coordinate reference system transformations
• Shapefile & GeoJSON parsing
• Topology validation & repair
• Geopandas dataframes explained
• Raster data handling with rasterio

Development

git clone https://github.com/python-geospatial/geopeek.git
cd geopeek
pip install -e ".[dev]"
pytest

Licence

MIT — see LICENSE.