Current release info

Name	Downloads	Version	Platforms
PyPI — pyramids-core (current)
PyPI — pyramids-gis (deprecated alias)			—
conda-forge — pyramids

pyramids-gis is the deprecated alias of pyramids-core. Install pyramids-core — the import name stays pyramids. pip install pyramids-gis still works (it depends on the matching pyramids-core and emits a FutureWarning), so existing pins keep resolving. The conda-forge package name is unchanged: pyramids.

conda-forge feedstock

Conda-forge feedstock

pyramids - GIS utility package

pyramids is a GIS utility package built on GDAL/OGR for working with raster data (GeoTIFF, NetCDF), vector data (shapefiles, GeoJSON), and multi-temporal datacubes. It provides a high-level, Pythonic API for reading, writing, cropping, reprojecting, aligning, mosaicking, and rasterizing geospatial data, with first-class support for Cloud Optimized GeoTIFFs, STAC catalogs, lazy/Dask computation, and cloud object stores (S3 / GCS / Azure / HTTPS).

Hold "Ctrl" to enable pan & zoom

flowchart LR
    subgraph Read["Read — any GDAL/OGR driver"]
        direction TB
        RAS["GeoTIFF · COG · ASCII<br/>NetCDF · GRIB · Zarr"]
        VEC["Shapefile · GeoJSON<br/>GeoPackage · GeoParquet"]
        STK["raster folder · archive<br/>STAC items"]
    end

    subgraph pyramids["pyramids"]
        direction TB
        DS["Dataset — single raster"]
        NC["NetCDF — variables · time"]
        DC["DatasetCollection — time stack"]
        FC["FeatureCollection — vector"]
        UG["UgridDataset — mesh"]
    end

    RAS -->|read_file| DS
    RAS -->|read_file| NC
    RAS -->|read_file| UG
    VEC -->|read_file| FC
    STK -->|from_files · from_stac| DC

    NC -.->|extends| DS
    DC -->|per timestep| DS
    FC -->|rasterize| DS
    DS -->|vectorize · contour| FC
    UG -->|to_dataset| DS

    subgraph Operate["Operate"]
        direction TB
        OPS["crop · reproject · resample · align<br/>mosaic · zonal stats · extract<br/>terrain · raster algebra · plot"]
        LAZY["lazy reads · reductions<br/>groupby — Dask"]
    end

    DS --- OPS
    DC --- LAZY

    OPS & LAZY -->|"to_file · to_cog · to_zarr<br/>to_netcdf · to_parquet"| OUT(["GeoTIFF · COG · NetCDF<br/>ASCII · Zarr · GeoParquet"])

Main Features

• GIS modules to enable the modeler to fully prepare the meteorological inputs and do all the preprocessing needed to build the model (align rasters with the DEM), in addition to various methods to manipulate and convert different forms of distributed data (rasters, NetCDF, shapefiles)
• Cloud Optimized GeoTIFF (COG) read, write, and validation, with transparent S3 / GCS / Azure / HTTPS support via GDAL's virtual filesystem. See the COG tutorial.

Installation

• Conda (conda-forge): Installing pyramids from the conda-forge channel can be achieved by:

conda install -c conda-forge pyramids

It is possible to list all the versions of pyramids available on your platform with:

conda search pyramids --channel conda-forge

• pip (PyPI):

to install the last release, you can easily use pip

pip install pyramids-core

The distribution was renamed pyramids-gis → pyramids-core (the import name stays pyramids). pip install pyramids-gis still works as a deprecated alias that pulls pyramids-core and warns on import — prefer pyramids-core for new installs.

• From source (latest):

to install the last development to time, you can install the library from GitHub

pip install git+https://github.com/serapeum-org/pyramids

Quick start

Minimal example: open a dataset and inspect metadata

from pyramids.dataset import Dataset

# Use your own raster path (GeoTIFF/ASC/NetCDF supported); here we show a relative test file
path = "tests/data/geotiff/dem.tif"  # adjust path as needed

ds = Dataset.read_file(path)
print(ds.columns, ds.rows, ds.geotransform)
print(ds.epsg, ds.cell_size, ds.no_data_value)

# Access array data
arr = ds.read_array()
print(arr.shape, arr.dtype)

# Save a single band to a new GeoTIFF (writes alongside input by default)
out = "./dem_copy.tif"
ds.to_file(out)
print("Saved to", out)

Next steps

• Explore the Tutorials for end-to-end workflows.
• See How it works for architecture and data flow.
• Browse the API Reference for details of classes and functions.