TerraTorch

1.2.6 verified Mon Apr 27 auth: no python

TerraTorch is a geospatial foundation model fine-tuning toolkit built on PyTorch Lightning, supporting models like Prithvi, DOFA, and others. The current version is 1.2.6, with active development and monthly releases.

pip install terratorch

Common errors

error ModuleNotFoundError: No module named 'terratorch' ↓

cause Library not installed or installed in wrong environment.

fix

Run pip install terratorch and ensure you're using Python >=3.10.

error AttributeError: module 'terratorch' has no attribute 'TerraTorchTrainer' ↓

cause Using an older version (<1.0) where the class was nested.

fix

Upgrade to the latest version: pip install --upgrade terratorch.

Warnings

breaking In v1.0, the import path for models changed from `terratorch.backbones` to `terratorch.models`. Old imports will fail. ↓

fix Use `from terratorch.models import PrithviModel` instead of `from terratorch.backbones import ...`.

gotcha `TerraTorchTrainer` requires a `model_name` that exactly matches a registered model key. Typos silently fall back to a default, causing unexpected behavior. ↓

fix List available models via `terratorch.models.list_models()` and use the exact string.

Imports

TerraTorchTrainer

wrong

from terratorch.trainer import TerraTorchTrainer

correct

from terratorch import TerraTorchTrainer

TerraTorchTrainer is now exposed at the top level.

PrithviModel

wrong

from terratorch.backbones import PrithviModel

correct

from terratorch.models import PrithviModel

Models are in the `models` module.

Quickstart

Minimal example fine-tuning a Prithvi model.

from terratorch import TerraTorchTrainer
from terratorch.datamodules import GeoSpatialDataModule
import os

trainer = TerraTorchTrainer(
    model_name='prithvi_eo_v2_300',
    backbone='prithvi_eo_v2_300',
    num_classes=10,
    learning_rate=1e-4,
)
datamodule = GeoSpatialDataModule(
    data_root=os.environ.get('DATA_ROOT', './data'),
    batch_size=4,
)
trainer.fit(datamodule=datamodule)