Skip to main content

stac-asset

GitHub Workflow Status Read the Docs PyPI Contributor Covenant

Download STAC Assets using a variety of authentication schemes.

Installation

python -m pip install stac-asset

To use the command-line interface (CLI):

python -m pip install 'stac-asset[cli]'

Usage

We have a Python API and a command-line interface (CLI).

API

Here's how to download a STAC Item and all of its assets to the current working directory. The correct client will be guessed from the assets' href. Each asset's href will be updated to point to the local file.

import pystac
import stac_asset
import asyncio


async def main():
    href = "https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json"
    item = pystac.read_file(href)
    item = await stac_asset.download_item(item, ".")
    return item


asyncio.run(main())

If you're working in a fully synchronous application, you can use our blocking interface:

import stac_asset.blocking

href = "https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json"
item = pystac.read_file(href)
item = stac_asset.blocking.download_item(item, ".")

Note that the above will not work in some environments like Jupyter notebooks which already have their own asyncio loop running. To get around this, you can use nest_asyncio. Simply run the following before using any functions from stac_asset.blocking.

import nest_asyncio

nest_asyncio.apply()

CLI

To download an item using the command line:

stac-asset download \
    https://raw.githubusercontent.com/radiantearth/stac-spec/master/examples/simple-item.json

To download all assets from the results of a pystac-client search, and save the item collection to a file named item-collection.json:

stac-client search https://planetarycomputer.microsoft.com/api/stac/v1 \
        -c landsat-c2-l2 \
        --max-items 1 | \
    stac-asset download > item-collection.json

If you'd like to only download certain assets, e.g. a preview image, you can use the include -i flag:

stac-client search https://planetarycomputer.microsoft.com/api/stac/v1 \
        -c landsat-c2-l2 \
        --max-items 1 | \
    stac-asset download -i rendered_preview -q

By default, all assets are stored in a folder named after the item ID. To change this, you can use the -p flag and specify a path template using PySTAC layout template variables:

stac-client search https://planetarycomputer.microsoft.com/api/stac/v1 \
        -c landsat-c2-l2 \
        --max-items 1 | \
    stac-asset download -i rendered_preview -p '${collection}'

See the documentation for more examples and complete API and CLI documentation.

Clients

This library comes with several clients, each tailored for a specific data provider model and authentication scheme. Some clients require some setup before use; they are called out in this table, and the details are provided below.

Name Description Notes
HttpClient Simple HTTP client without any authentication
S3Client Simple S3 client Use requester_pays=True in the client initializer to enable access to requester pays buckets, e.g. USGS landsat's public AWS archive
FilesystemClient Moves files from place to place on a local filesystem Mostly used for testing
PlanetaryComputerClient Signs urls with the Planetary Computer Authentication API No additional setup required, works out of the box
EarthdataClient Uses a token-based authentication to download data, from some Earthdata providers, e.g. DAACs Requires creation of a personal access token, see docs

For information about configuring each client, see the API documentation for that client.

Versioning

This project does its best to adhere to semantic versioning. Any module, class, constant, or function that does not begin with a _ is considered part of our public API for versioning purposes. Our command-line interface (CLI) is NOT considered part of our public API, and may change in breaking ways at any time. If you need stability promises, use our API.

Contributing

Use Github issues to report bugs and request new features. Use Github pull requests to fix bugs and propose new features.

Developing

Install uv. Then clone, sync, and install pre-commit:

git clone git@github.com:stac-utils/stac-asset.git
cd stac-asset
uv sync
pre-commit install

Testing

Some network-touching tests are disabled by default. To enable these tests:

uv run pytest --network-access

Some tests are client-specific and need your environment to be configured correctly. See each client's documentation for instructions on setting up your environment for each client.

Docs

To build:

make -C docs html && open docs/_build/html/index.html

It can be handy to use sphinx-autobuild if you're doing a lot of doc work:

uv pip install sphinx-autobuild
sphinx-autobuild --watch src docs docs/_build/html

License

Apache-2.0

Metadata

Release files for stac-asset 0.4.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for stac-asset 0.4.8
File Size Uploaded Provenance Actions
stac_asset-0.4.8.tar.gz 261.1 kB With provenance Details for stac_asset-0.4.8.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for stac-asset 0.4.8
File Interpreter ABI Platform Actions
stac_asset-0.4.8-py3-none-any.whl Python 3 none any Details for stac_asset-0.4.8-py3-none-any.whl

Total release size: 298.3 kB

Release files / stac_asset-0.4.8.tar.gz

Download URL stac_asset-0.4.8.tar.gz
Size 261.1 kB
Tags Source
SHA-256 checksum
How to use checksums
cb7ac55edd00e5cc024314ecba8af84f169d9e2c136d113857f461c420772dc6
BLAKE2b-256 checksum
How to use checksums
be1e4c9b8fd9c6490957075582f0cd34bac425681a88ce70a8f9c1bff1208f86
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.

Transparency log

Release files / stac_asset-0.4.8-py3-none-any.whl

Download URL stac_asset-0.4.8-py3-none-any.whl
Size 37.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
1aa9e8d9f1fe9667912cb5f5de3187d1213c854e592d634a6421a96c866eb28e
BLAKE2b-256 checksum
How to use checksums
fddb80d789bf93c1ff6a59f40173644a513f855a74fea0b1791f115d4386823d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.

Transparency log

Security for stac-asset 0.4.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for stac_asset-0.4.8.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page