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
muslpy 3.10–3.915 runs
installs and imports cleanly · install 0.0s · import 0.109s · 24.8MB
glibcpy 3.10–3.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.fixFor 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.fixUpdate 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.fixUse `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.fixEnsure `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.fixWhen 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`.
fixInstall `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.
fixEnsure 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.
fixCreate 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.
fixUse 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.