Registry / data / pystac

pystac

JSON →
library1.15.2pypypi✓ verified 25d ago

PySTAC is a Python library for working with the SpatioTemporal Asset Catalog (STAC) specification. It provides tools for reading, creating, and modifying STAC Catalogs, Collections, and Items. Currently at version 1.14.3, the library maintains a regular release cadence with updates addressing bug fixes and new features, including support for the latest STAC specification versions.

pip install pystac
INSTALL
IMPORT
SIG · PYSTAC
P
pystac
datapythonv1.15.2
Install
2.9s avg
Import
104ms
Disk
23MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.15.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.915 runs
installs and imports cleanly · install 0.0s · import 0.109s · 24.8MB
glibc
py 3.103.915 runs
installs and imports cleanly · install 2.9s · import 0.099s · 25MB
23MB installed
● package 23MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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
from pystac import STAC_VERSION
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
from pystac.extensions 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.

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()
Debug
Known issues
breakingPySTAC 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.
affects: >=1.12.0
breakingAs 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.
affects: >=1.14.x (expected in future minor/major release, announced Spring 2026)
gotchaManually 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.
affects: All versions
gotchaValidation 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]'`.
affects: All versions
gotchaAsset 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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'fsspec'
PySTAC uses `fsspec` for abstracting filesystem access to remote locations like S3 or Google Cloud Storage, but `fsspec` and its specific backend implementations (e.g., `s3fs`, `gcsfs`) are optional dependencies and are not installed by default with `pip install pystac`.
fix
Install `pystac` with the `io` extra for general remote filesystem support, or specify a backend like `s3` or `gcs` for specific cloud storage access:
```bash
pip install "pystac[io]"
# Or for S3 specific:
pip install "pystac[s3]"
```
pystac.errors.STACValidationError
This error occurs when a PySTAC object (e.g., Item, Collection, Catalog) does not conform to the STAC specification, often due to missing required fields, incorrect data types, or invalid structure.
fix
Ensure all required STAC fields are present and correctly formatted according to the specification. Use the `.validate()` method on the object to get detailed validation errors and pinpoint the exact issue:
```python
import pystac

# Assuming 'item' is your pystac.Item object
try:
    item.validate()
    print("STAC Item is valid!")
except pystac.errors.STACValidationError as e:
    print(f"Validation failed: {e}")
    # Often, e.validation_errors provides more details
    for error in e.validation_errors:
        print(f"  - {error.message}")
```
AttributeError: 'Catalog' object has no attribute 'add_item'
In PySTAC, `Item` objects are generally added to `Collection` objects, not directly to `Catalog` objects. `Catalog` objects primarily manage child `Catalog`s or `Collection`s.
fix
Create a `Collection` object, add your `Item` to it using `collection.add_item()`, and then add the `Collection` to your `Catalog` using `catalog.add_child()`:
```python
import pystac

catalog = pystac.Catalog(id='my-catalog', description='My root catalog')
collection = pystac.Collection(
    id='my-collection',
    description='A collection of items',
    extent=pystac.Extent(
        spatial=pystac.SpatialExtent([[0, 0, 10, 10]]),
        temporal=pystac.TemporalExtent([[None, None]])
    )
)
# Assuming 'my_item' is a pystac.Item object
# collection.add_item(my_item)
catalog.add_child(collection)
```
AttributeError: module 'pystac' has no attribute 'read_json'
The `pystac.read_json` function was deprecated and later removed in favor of more object-oriented class methods for loading STAC objects from files.
fix
Use the `from_file` class method specific to the STAC object type you are trying to load (e.g., `Catalog.from_file`, `Collection.from_file`, or `Item.from_file`).
```python
import pystac

# To load a STAC Catalog
catalog = pystac.Catalog.from_file('path/to/catalog.json')

# To load a STAC Item
item = pystac.Item.from_file('path/to/item.json')

# To load a STAC Collection
collection = pystac.Collection.from_file('path/to/collection.json')
```
Upgrade
Version history
1.15.2latest on PyPI · released Jul 27, 2026
Audit
Dependencies
python-dateutilrequiredCore dependency for date/time handling.
jsonschemaoptionalRequired for STAC object validation when `pystac[validation]` is installed.
orjsonoptionalOptional dependency for faster JSON operations when `pystac[orjson]` is installed.
urllib3optionalOptional dependency for features like `RetryStacIO` when `pystac[urllib3]` is installed.
jinja2optionalOptional dependency for pretty display of PySTAC objects in Jupyter notebooks when `pystac[jinja2]` is installed.
Agent activity
12 hits · last 30 days
node
10
Resources