{"id":3768,"library":"pystac","title":"PySTAC","description":"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.","status":"active","version":"1.14.3","language":"en","source_language":"en","source_url":"https://github.com/stac-utils/pystac","tags":["stac","geospatial","catalog","satellite","earth-observation","metadata"],"install":[{"cmd":"pip install pystac","lang":"bash","label":"Core library"},{"cmd":"pip install 'pystac[validation]'","lang":"bash","label":"With validation support (jsonschema)"},{"cmd":"pip install 'pystac[orjson]'","lang":"bash","label":"With faster JSON serialization/deserialization (orjson)"}],"dependencies":[{"reason":"Core dependency for date/time handling.","package":"python-dateutil","optional":false},{"reason":"Required for STAC object validation when `pystac[validation]` is installed.","package":"jsonschema","optional":true},{"reason":"Optional dependency for faster JSON operations when `pystac[orjson]` is installed.","package":"orjson","optional":true},{"reason":"Optional dependency for features like `RetryStacIO` when `pystac[urllib3]` is installed.","package":"urllib3","optional":true},{"reason":"Optional dependency for pretty display of PySTAC objects in Jupyter notebooks when `pystac[jinja2]` is installed.","package":"jinja2","optional":true}],"imports":[{"symbol":"Catalog","correct":"from pystac import Catalog"},{"symbol":"Collection","correct":"from pystac import Collection"},{"symbol":"Item","correct":"from pystac import Item"},{"symbol":"Asset","correct":"from pystac import Asset"},{"symbol":"Link","correct":"from pystac import Link"},{"note":"STAC_VERSION was removed/refactored; use pystac.version.STACVersion.DEFAULT_STAC_VERSION or pystac.get_stac_version() for current version.","wrong":"from pystac import STAC_VERSION","symbol":"STACVersion","correct":"from pystac.version import STACVersion"},{"note":"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.","wrong":"from pystac.extensions import EOExtension","symbol":"EOExtension","correct":"from pystac.extensions.eo import EOExtension"}],"quickstart":{"code":"import pystac\nfrom datetime import datetime, timezone\nfrom shapely.geometry import Polygon, mapping\nfrom tempfile import TemporaryDirectory\nimport os\n\n# 1. Create a temporary directory for the STAC catalog\ntmp_dir = TemporaryDirectory()\ncatalog_dir = os.path.join(tmp_dir.name, 'my_stac_catalog')\n\n# 2. Create a root Catalog\ncatalog = pystac.Catalog(\n    id='example-catalog',\n    description='A simple example STAC Catalog for demonstration.'\n)\n\n# 3. Create an Item\n# Define spatial and temporal extents for the item\nbbox = [-10.0, -10.0, 10.0, 10.0]\ngeometry = mapping(Polygon.from_bounds(*bbox))\n\n# Create a datetime object for the item\ndt = datetime(2023, 1, 1, 12, 0, 0, tzinfo=timezone.utc)\n\n# Create a STAC Item\nitem = pystac.Item(\n    id='example-item-1',\n    geometry=geometry,\n    bbox=bbox,\n    datetime=dt,\n    properties={}\n)\n\n# Add an asset to the item\nasset_href = 'https://example.com/data/image.tif'\nitem.add_asset(\n    key='image',\n    asset=pystac.Asset(\n        href=asset_href,\n        media_type=pystac.MediaType.GEOTIFF,\n        roles=['data']\n    )\n)\n\n# 4. Add the item to the catalog\ncatalog.add_item(item)\n\n# 5. Normalize HREFs and save the catalog\ncatalog.normalize_hrefs(catalog_dir)\ncatalog.save(catalog_type=pystac.CatalogType.SELF_CONTAINED)\n\nprint(f\"STAC Catalog saved to: {catalog_dir}\")\n\n# Clean up the temporary directory (optional)\n# tmp_dir.cleanup()","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=1.12.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.14.x (expected in future minor/major release, announced Spring 2026)"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure `pystac` is installed with the `validation` extra: `pip install 'pystac[validation]'`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}