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. Point it at a whole folder and it triages every dataset in one table.

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 — worse — declared but wrong? geopeek cross-checks the coordinates against the CRS and flags a projected label sitting on lon/lat data (and vice versa).
• Are there invalid, empty, null, or duplicate geometries? Invalid ones come with the self-intersection reason attached.
• Are geometry types mixed, or do features carry Z coordinates that downstream code will silently drop?
• Is a GeoTIFF actually cloud-optimized? geopeek reports tiling, overviews and compression so you know before you upload it as a COG.
• 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 data/                        # scan every dataset in a folder
geopeek incoming.gpkg --check        # quiet CI gate: silent unless something is wrong

The CLI exits with status 1 when warnings are emitted — handy in CI pipelines that vet incoming data. The --check flag turns that into a quiet gate (no output on a clean file), and pointing geopeek at a directory triages every recognised file at once.

Scanning a folder

                                geopeek scan
┏━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┓
┃ File           ┃ Kind   ┃ Summary                          ┃       Health ┃
┡━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━┩
│ parcels.gpkg   │ vector │ 8123 feat · EPSG:25832           │ ok           │
│ ortho.tif      │ raster │ 1024×1024 · EPSG:32632 · not-COG │ 4 warning(s) │
└────────────────┴────────┴──────────────────────────────────┴──────────────┘

2 file(s) scanned · 1 clean · 1 flagged

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) · not cloud-optimized │
╰──────────────────────────────────────────────────────────╯
  CRS          EPSG:25832
  Bounds       (500000, 6640000) → (540960, 6680960)
  Pixel size   10 × 10
  Dtypes       float32
  Nodata       -9999.0
  Tiling       striped (1×4096)
  Overviews    none

  ┌─ Warnings ────────────────────────────────────────────────┐
  │ • GeoTIFF is striped, not tiled — not cloud-optimized;    │
  │   windowed reads fetch whole strips.                      │
  │ • No internal overviews — zoomed-out reads decode full    │
  │   resolution; add overviews for a COG.                    │
  └───────────────────────────────────────────────────────────┘

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
• Cloud-native geospatial formats
• 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.