PySTAC

Warnings

• breaking PySTAC v1.12.0 changed the default STAC specification version to 1.1.0. This means new catalogs created or existing catalogs processed by PySTAC will default to 1.1.0. Users working with older STAC versions should be aware of potential migration needs or explicitly set the STAC version.
  Fix: For existing catalogs, use `catalog.migrate_to_version('1.0.0')` if you need to downgrade, or explicitly set `pystac.set_stac_version('1.0.0')` before writing. For new catalogs, ensure compatibility with 1.1.0 or set the version.
• breaking As of Spring 2026, STAC extension implementations (e.g., Electro-Optical, Projection) have moved from being part of the core `pystac` package to their own independent Python packages (e.g., `pystac-ext-projection`). This is a breaking change for how extensions are accessed and versioned.
  Fix: Update your imports to use the new extension packages (e.g., `from pystac_ext_projection import ProjectionExtension`). Consult the `pystac` GitHub repository for specific package names and versioning.
• gotcha Manually setting `pystac.set_stac_version()` or the `PYSTAC_STAC_VERSION_OVERRIDE` environment variable only alters the `stac_version` property written to JSON. It does not change the internal object structure or enforce validation against that specific version, potentially leading to invalid STAC.
  Fix: Use `pystac.set_stac_version()` only if you are certain the objects conform to the specified version's structure. For robust version compatibility, use `catalog.migrate_to_version()` which attempts to convert the structure.
• gotcha Validation functionality in PySTAC requires the optional `jsonschema` dependency. If you attempt to call `.validate()` methods without installing `pystac[validation]`, it will result in an error or unexpected behavior.
  Fix: Ensure `pystac` is installed with the `validation` extra: `pip install 'pystac[validation]'`.
• gotcha Asset HREFs (paths to data) can be absolute or relative. Relative HREFs are resolved based on the Item's metadata file location. Incorrect handling of relative paths can lead to broken links in generated STAC catalogs.
  Fix: When creating STAC objects, use `catalog.normalize_hrefs()` to correctly set all relative links based on a root directory. Be mindful of how you construct relative vs. absolute paths, especially when working with remote assets.

Install

• pip install pystac Core library
• pip install 'pystac[validation]' With validation support (jsonschema)
• pip install 'pystac[orjson]' With faster JSON serialization/deserialization (orjson)

Imports

• Catalog

  from pystac import Catalog

• Collection

  from pystac import Collection

• Item

  from pystac import Item

• Asset

  from pystac import Asset

• Link

  from pystac import Link

• STACVersion

  from pystac.version import STACVersion

  STAC_VERSION was removed/refactored; use pystac.version.STACVersion.DEFAULT_STAC_VERSION or pystac.get_stac_version() for current version.
• EOExtension

  from pystac.extensions.eo import EOExtension

  Extensions are imported from their specific submodules, e.g., `pystac.extensions.eo`. As of Spring 2026, extension implementations are moving to their own packages, which might change import paths in future major versions.

Quickstart

This quickstart demonstrates how to create a basic PySTAC Catalog, add an Item with an Asset, and save it to disk as a self-contained catalog. It uses `shapely` for geometry creation and `tempfile` for directory management.

import pystac
from datetime import datetime, timezone
from shapely.geometry import Polygon, mapping
from tempfile import TemporaryDirectory
import os

# 1. Create a temporary directory for the STAC catalog
tmp_dir = TemporaryDirectory()
catalog_dir = os.path.join(tmp_dir.name, 'my_stac_catalog')

# 2. Create a root Catalog
catalog = pystac.Catalog(
    id='example-catalog',
    description='A simple example STAC Catalog for demonstration.'
)

# 3. Create an Item
# Define spatial and temporal extents for the item
bbox = [-10.0, -10.0, 10.0, 10.0]
geometry = mapping(Polygon.from_bounds(*bbox))

# Create a datetime object for the item
dt = datetime(2023, 1, 1, 12, 0, 0, tzinfo=timezone.utc)

# Create a STAC Item
item = pystac.Item(
    id='example-item-1',
    geometry=geometry,
    bbox=bbox,
    datetime=dt,
    properties={}
)

# Add an asset to the item
asset_href = 'https://example.com/data/image.tif'
item.add_asset(
    key='image',
    asset=pystac.Asset(
        href=asset_href,
        media_type=pystac.MediaType.GEOTIFF,
        roles=['data']
    )
)

# 4. Add the item to the catalog
catalog.add_item(item)

# 5. Normalize HREFs and save the catalog
catalog.normalize_hrefs(catalog_dir)
catalog.save(catalog_type=pystac.CatalogType.SELF_CONTAINED)

print(f"STAC Catalog saved to: {catalog_dir}")

# Clean up the temporary directory (optional)
# tmp_dir.cleanup()