TerraTorch: a fine-tuning harness for geospatial foundation models
A Python toolkit for fine-tuning Geospatial Foundation Models (GFMs).
At a glance
- What is it?
- TerraTorch is an Apache-2.0 PyTorch library that wraps pretrained geospatial backbones in Lightning trainers, model factories and configurable datamodules. It is a training framework, not a model zoo, and the README is explicit that no models are hosted.
- Who is it for?
- TerraTorch is worth adopting if you already train geospatial models in PyTorch and want Prithvi, TerraMind, Clay or timm backbones wired to SMP or mmsegmentation decoders through Lightning and YAML configs. Skip it if you want a hosted model endpoint or have no GDAL in your build image.
- Can I use it commercially?
- Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap TerraTorch fills between pretrained checkpoints and your labels
Geospatial foundation models ship as weights and a paper, not as a training pipeline. Getting from a Prithvi or TerraMind checkpoint to a segmentation model on your own tiles means writing a datamodule that understands multispectral bands, picking a decoder, matching normalisation statistics, and wiring the whole thing into a training loop. That plumbing is repetitive and easy to get subtly wrong, and it is the part TerraTorch targets. The README describes it as a PyTorch domain library built on PyTorch Lightning and TorchGeo, with flexible trainers for image segmentation, classification and pixel-wise regression. The intended user is an engineer or researcher who already has labelled geospatial data and wants to fine-tune rather than pretrain. It is not aimed at someone who wants a prediction API, and it is not aimed at someone who has never trained a model. The three task types it names are the scope: segmentation, classification, pixel-wise regression. If your problem is object detection, the README mentions DETR and Deformable DETR only in the context of optional test dependencies, not as a documented first-class task.
Model factories, backbones and decoders as separate pieces
The architecture visible in the README separates backbones from decoders and joins them through model factories. Backbones come from several places: open pretrained geospatial models (Prithvi, TerraMind, SatMAE, ScaleMAE, Clay, plus Satlas, DOFA, SSL4EO-L and SSL4EO-S12 as implemented in TorchGeo), and the wider timm collection. Decoders come from SMP and mmsegmentation. That split is the design decision that matters most. It means a fine-tuning run is a composition problem rather than a code-writing problem, and it means you can swap a decoder without touching the backbone loading path. The cost is that you inherit the constraints of every upstream package at once: a decoder that exists in mmsegmentation but not in SMP is only reachable through the mmsegmentation path, and a backbone's expected band count and input resolution have to match whatever your datamodule feeds it. TerraTorch does not remove that matching work, it just gives you a place to declare it. The README also lists ready-to-go datasets and datamodules, described as requiring only that you point at your data with no need for custom classes, and it names GEO-Bench and all TorchGeo datasets as included.
Installing it, and the GDAL problem you inherit
Installation is a single command from PyPI: pip install terratorch, or pip install terratorch==<version> for a pinned point release. The README notes that pyproject.toml requires pip>=21.8, and suggests python -m pip install --upgrade pip if needed. Conda users can run conda install -c conda-forge terratorch. There is also a pipx route, pipx install terratorch, which the README describes as creating an isolated environment so the tool can be run from the command line without activating an environment. The dependency that will decide whether your install succeeds is GDAL. The README states plainly that TerraTorch requires GDAL and that installing it can be quite a complex process, recommending a conda environment with conda install -c conda-forge gdal, and noting that installing from conda-forge probably avoids the problem. Two optional extras exist. RF-DETR support is installed with pip install terratorch[rfdetr], and for editable contributor installs with pip install -e .[test,rfdetr]. Deformable DETR needs CUDA operators for MultiScaleDeformableAttention compiled from the Deformable-DETR repository, though the README states core DETR functionality works without the extension and the relevant tests are skipped when the operators are absent. The README also shows launching fine-tuning tasks through a CLI with configuration files, or from Jupyter notebooks, but it does not reproduce the CLI invocation in the excerpt available here.
No models are hosted, and the licence burden lands on you
This is the limitation that deserves the most attention, and the project states it rather than burying it. The README carries a disclaimer that TerraTorch provides tools for fine-tuning and using pretrained models, that no models are hosted by TerraTorch, and that it only provides the training and inference framework. It then assigns responsibility: it is the sole responsibility of the user to verify that the licence of any model they download, fine-tune or deploy allows their intended use, and the maintainers state they do not provide legal advice and are not liable for misuse of third-party models. Read that as an operating constraint rather than boilerplate. TerraTorch's own Apache-2.0 licence covers the library code. It does not cover Prithvi, TerraMind, Clay, SatMAE or any timm checkpoint you pull in, and those carry their own terms. A team that treats the Apache-2.0 badge on the repository as clearance for the whole pipeline has misread the situation, and the README says so. There is a second, quieter limitation: because the library is a composition layer, its capabilities are bounded by what upstream packages expose at any given moment, and the README frames several integrations as optional extras rather than core paths.
How TerraTorch differs from using TorchGeo directly
The obvious alternative is TorchGeo on its own. TerraTorch is built on top of it, and the README lists all TorchGeo datasets and datamodules as available through TerraTorch, so the two are not in competition over data loading. The difference is what sits above it. TorchGeo gives you geospatial datasets, samplers and transforms, and leaves the training loop, the decoder selection and the checkpoint loading to you. TerraTorch adds the Lightning trainers, the model factories that pair backbones with decoders, and the configuration-file-driven CLI. If your work is dataset research, benchmarking samplers, or building something that does not resemble a standard fine-tuning run, TorchGeo alone is less machinery to fight. If your work is repeatedly fine-tuning pretrained backbones on new label sets, the factory and trainer layer is the part that saves time. A second alternative for pure segmentation work is SMP directly, which TerraTorch already uses as a decoder source. Going straight to SMP means you lose the geospatial band handling and the pretrained GFM loading paths, and you write the multispectral input pipeline yourself. The README also points to a separate HPO/NAS tool, Iterate, for hyperparameter and architecture search, which suggests the maintainers see search as a different problem from fine-tuning rather than something TerraTorch absorbs.
Release cadence and what upgrading actually costs
The release history shows v1.2.10 and v1.2.9 both dated 2026-07-15, followed by v1.2.8 on 2026-05-29, with the last push to main on 2026-08-31. Two releases on the same day points to a packaging or hotfix correction rather than two feature drops, and the README's own advice, pip install terratorch==<version>, is the sensible posture for anything you intend to reproduce. The maintenance cost that matters here is not TerraTorch's own version churn but the surface area underneath it. A fine-tuning run depends on PyTorch Lightning, TorchGeo, timm, SMP or mmsegmentation, and GDAL, and the README treats GDAL as the install step most likely to go wrong. Upgrading TerraTorch means re-validating that stack, and if you pin TerraTorch you should pin the rest alongside it. On licensing, Apache-2.0 is permissive and imposes no copyleft obligation on your training code, but it says nothing about the weights you load. The disclaimer in the README is the operative document there, and it puts verification on you.
Who should adopt TerraTorch, and what to check before you do
Adopt it if you are fine-tuning segmentation, classification or pixel-wise regression models on geospatial data, you already work in PyTorch and Lightning, and you want Prithvi, TerraMind, Clay, SatMAE, ScaleMAE or timm backbones available alongside SMP and mmsegmentation decoders without writing the glue each time. The CLI plus configuration-file workflow and the Jupyter path both exist for that reason, and the GEO-Bench and TorchGeo datamodules mean you can start on a public benchmark before touching your own tiles. Do not adopt it if you need a served model, since the README is explicit that no models are hosted and TerraTorch is only the training and inference framework. Do not adopt it if your environment cannot carry GDAL, or if your task is object detection at production scale, where the README treats DETR support as optional and partly test-only. Before you commit, verify two things. First, the licence on the specific checkpoint you plan to fine-tune, because the Apache-2.0 licence on this repository does not travel with the weights. Second, that GDAL resolves cleanly in your target image, since the README's own recommendation is a conda-forge install and that will not match every CI setup.
Editorial conclusion
TerraTorch is worth adopting if you already train geospatial models in PyTorch and want Prithvi, TerraMind, Clay or timm backbones wired to SMP or mmsegmentation decoders through Lightning and YAML configs. Skip it if you want a hosted model endpoint or have no GDAL in your build image. Before committing, verify that the specific checkpoint you intend to fine-tune carries a licence that permits your use, and confirm your GDAL install path works in the target environment.
Community notes