Installation

Install Rasteret and optional dependencies for your workflow

Installation

Rasteret requires Python 3.12+ and is available on PyPI.

Basic Installation

uv (Recommended)

uv pip install rasteret

uv is a fast Python package installer and resolver written in Rust.

pip

pip install rasteret

The basic installation includes all dependencies needed for building Collections from STAC APIs and reading data as NumPy arrays or GeoPandas DataFrames.

Optional Extras

Rasteret provides optional extras for specific workflows. Install only what you need:

xarray Support

For analysis workflows using xarray:

uv pip install "rasteret[xarray]"

Includes: xarray (≥2024.1.0)

Use when: You want to use collection.get_xarray() for analysis, visualization, or geospatial computations.

TorchGeo Integration

For ML training with PyTorch and TorchGeo:

uv pip install "rasteret[torchgeo]"

Includes: torchgeo (≥0.9.0)

Use when: You want to use collection.to_torchgeo_dataset() for training with PyTorch DataLoader, TorchGeo samplers, and transforms.

Cloud Provider Authentication

AWS (S3)

For requester-pays buckets (Landsat, NAIP, etc.):

uv pip install "rasteret[aws]"

Includes: boto3 (≥1.34.0)

Use when: Working with AWS S3 requester-pays datasets like:

• Landsat Collection 2 on Earth Search
• NAIP imagery
• Any S3-hosted dataset requiring AWS credentials

You must configure AWS credentials before using requester-pays data:

aws configure

Or set environment variables:

export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret
export AWS_REGION=us-west-2

Azure (Planetary Computer)

For Microsoft Planetary Computer signed URLs:

uv pip install "rasteret[azure]"

Includes: planetary-computer (≥1.0.0), requests (≥2.31.0)

Use when: Accessing datasets from Microsoft Planetary Computer:

• Sentinel-2 on Planetary Computer
• ALOS DEM
• NASADEM
• ESA WorldCover
• USDA Cropland Data Layer

Planetary Computer requires signing up for a free API key at planetarycomputer.microsoft.com.

NASA Earthdata

For NASA LP DAAC and Earthdata-hosted collections:

uv pip install "rasteret[earthdata]"

Includes: requests (≥2.31.0)

Use when: Accessing NASA datasets requiring Earthdata credentials.

Configure credentials in ~/.netrc:

machine urs.earthdata.nasa.gov
login YOUR_USERNAME
password YOUR_PASSWORD

Combining Extras

Install multiple extras by combining them with commas:

# ML workflow with AWS access
uv pip install "rasteret[torchgeo,aws]"

# Analysis workflow with xarray and Azure
uv pip install "rasteret[xarray,azure]"

# Complete installation (not recommended unless you need everything)
uv pip install "rasteret[xarray,torchgeo,aws,azure,earthdata]"

Verify Installation

Check that Rasteret is installed correctly:

import rasteret

print(rasteret.__version__)
# Output: 0.x.x

List available datasets:

rasteret datasets list

You should see a table of built-in datasets with their IDs, names, coverage, and authentication requirements.

Python Version Requirements

Rasteret Version	Python Version
0.x.x (current)	≥3.12

Rasteret requires Python 3.12 or newer. If you’re using an older Python version, you must upgrade:

# Using uv
uv python install 3.12

# Using pyenv
pyenv install 3.12
pyenv local 3.12

Core Dependencies

The base installation includes:

• numpy (≥1.24.0) — Array operations
• pyarrow (≥14.0.1) — Parquet reading/writing
• pystac-client (≥0.7.5) — STAC API client
• obstore (≥0.8.0) — Object storage I/O
• geopandas (≥0.13) — Geospatial DataFrames
• rasterio (≥1.4.3, <1.5.0) — GeoTIFF metadata
• pyproj (≥3.6.1) — CRS transformations
• affine (≥2.4.0) — Affine transformations
• imagecodecs (≥2023.9.18) — Image compression codecs

These are installed automatically and require no extra configuration.

System Requirements

Operating Systems

✅ Linux (primary development platform)
✅ macOS (Intel and Apple Silicon)
✅ Windows (via WSL2 recommended)

Hardware

Minimum:

• 4 GB RAM
• 2 CPU cores
• 1 GB disk space for workspace cache

Recommended:

• 16+ GB RAM for large collections
• 4+ CPU cores for parallel COG header parsing
• SSD for workspace cache

Collections are stored as Parquet files in ~/rasteret_workspace/ by default. A typical collection with 1000 scenes uses 10-50 MB of disk space.

Troubleshooting

ImportError: No module named ‘rasteret’

Ensure you’re using Python 3.12+:

python --version
# Should show Python 3.12.x or higher

GDAL/Rasterio Issues

Rasterio is only used for metadata parsing, not pixel I/O. If you encounter GDAL errors:

1. Update rasterio:

   uv pip install --upgrade rasterio
   

2. If problems persist, Rasteret can work without rasterio for some workflows (using obstore directly).

AWS Credentials Not Found

For requester-pays datasets:

# Configure AWS CLI
aws configure

# Or set environment variables
export AWS_ACCESS_KEY_ID=...
export AWS_SECRET_ACCESS_KEY=...
export AWS_DEFAULT_REGION=us-west-2

Planetary Computer Authentication

Sign up for a free API key and configure:

import planetary_computer as pc
pc.set_subscription_key("YOUR_KEY")

Next Steps

Quickstart

Build your first Collection and fetch pixels in 5 minutes