Deploy Prithvi-EO-2.0: Earth Observation Foundation Model Guide

Here’s an unpopular take: for 90% of Earth observation tasks, you don’t need the 600M Prithvi model. You need the 300M-TL variant, and picking the wrong one is the single most common deploy mistake I see.

This guide walks through installing Prithvi-EO-2.0, the Earth observation foundation model from NASA, IBM, and the Jülich Supercomputing Centre. Released December 4, 2024, it’s a Vision Transformer trained on 4.2M Harmonized Landsat and Sentinel-2 samples. Skip the marketing tour – straight to commands.

Pick the right Prithvi variant first

Four checkpoints on Hugging Face. This is the decision most tutorials skip entirely, then wonder why downstream tasks underperform.

The “TL” suffix means the model was pretrained with temporal and location embeddings – center lat/long plus day-of-year. The 600M-TL beats the previous Prithvi-EO by 8% on GEO-Bench and outperforms six other geospatial foundation models across resolutions from 0.1m to 15m (per the arXiv paper, December 2024). That 8% number gets quoted everywhere. What doesn’t: the improvement comes disproportionately from the TL embeddings, not raw parameter count. Download the non-TL 600M and you’re paying for compute you can’t cash in.

Think of TL embeddings like EXIF data for satellite images – the model doesn’t just see pixels, it knows where on Earth and when in the year those pixels were captured. Strip that out and you’ve got a model flying blind over geography and seasons.

System requirements

OS: Linux strongly recommended (Ubuntu 22.04+ tested). macOS works with caveats. Windows: use WSL2.

Python: 3.10, 3.11, or 3.12 – TerraTorch is tested for 3.10 <= Python <= 3.12 (as of the 1.2.1 release, January 2026).

GPU: NVIDIA with at least 16GB VRAM for the 300M models; 24GB+ for 600M fine-tuning (rough estimates – actual usage varies by batch size and tile resolution). CPU-only inference works but is slow.

RAM/Disk: 16GB RAM minimum, 32GB recommended when loading multi-temporal tiles. Reserve ~10GB for checkpoints plus dependencies, 50GB+ for real HLS workloads. These are practical estimates, not official specs.

System deps: GDAL. This is where installs die. More below.

Install TerraTorch 1.2.1 (the recommended path)

The clean deploy path runs through TerraTorch, the official fine-tuning toolkit maintained by IBM. PyPI release 1.2.1 landed January 7, 2026 – current stable.

# Create isolated conda env - this handles GDAL for you
conda create -n prithvi python=3.11 -y
conda activate prithvi

# Install GDAL from conda-forge FIRST
conda install -c conda-forge gdal -y

# Then TerraTorch
pip install --upgrade pip
pip install terratorch==1.2.1

# Verify
python -c "import terratorch; print(terratorch.__version__)"

Why conda first? Turns out TerraTorch’s docs are direct about it: GDAL “can be quite a complex process” to install, and the pip-only path fails silently on many systems. Conda-forge sidesteps that entirely.

Watch out: the official Prithvi-EO-2.0 requirements.txt pins TerraTorch to a specific commit via SSH – git+ssh://[email protected]/IBM/terratorch.git@ca289f0663.... Anyone without SSH keys configured on GitHub hits a permission error immediately. See Error #4 below for the fix.

Download the model checkpoint

Prithvi weights live on Hugging Face under the ibm-nasa-geospatial org. TerraTorch fetches them automatically when you reference the backbone, but pulling manually is faster for offline setups.

pip install huggingface_hub
huggingface-cli download ibm-nasa-geospatial/Prithvi-EO-2.0-300M-TL 
 --local-dir ./checkpoints/prithvi-300m-tl

The band-order trap (read this before touching any config)

The model was pretrained on exactly six HLS bands, in this order: Blue, Green, Red, Narrow NIR, SWIR1, SWIR2. Feed Sentinel-2 tiles in native band order – starts with B01 coastal aerosol – and Prithvi produces output. Garbage output. No error, no warning. The model card specifies the band order explicitly; most people skip that page entirely.

Quick config for a semantic segmentation task using the TerraTorch CLI:

# config.yaml (excerpt)
model:
 class_path: terratorch.tasks.SemanticSegmentationTask
 init_args:
 model_args:
 backbone: prithvi_eo_v2_300_tl
 backbone_pretrained: true
 backbone_bands:
 - BLUE
 - GREEN
 - RED
 - NIR_NARROW
 - SWIR_1
 - SWIR_2
 backbone_num_frames: 1
 decoder: UperNetDecoder
 decoder_channels: 256
 num_classes: 2
 necks:
 - name: SelectIndices
 indices: [5, 11, 17, 23]
 - name: ReshapeTokensToImage

The necks block is non-optional for ViT backbones – it selects intermediate transformer layers and reshapes tokens back into a spatial grid the decoder can consume. Skip it and your loss won’t converge.

Verify it works

Two sanity checks. Either takes under a minute.

Option A – image reconstruction inference. The official Prithvi-EO-2.0 repo ships an inference.py that reconstructs masked patches from HLS tiles:

python inference.py --data_files t1.tif t2.tif t3.tif t4.tif

Four geotiffs in chronological order, all reflectance units. No NaN warning in output = channels aligned, checkpoint loaded.

Option B – TerraTorch fit dry run. Point the CLI at a downstream example config from the TerraTorch-Examples repo:

terratorch fit -c configs/prithvi_v2_eo_300_tl_unet_multitemporal_crop.yaml 
 --trainer.fast_dev_run true

fast_dev_run runs one batch and exits. Survives = working stack.

Common errors and fixes

1. EntryNotFoundError: 404 for Prithvi_100M.pt – GitHub issue #301 documents this: the old Prithvi-EO-1.0 checkpoint URL is broken. Fix: swap the v1 backbone name (prithvi_vit_100) for a v2 one like prithvi_eo_v2_300_tl.

2. OSError: [Errno cannot find] libgdal.so – GDAL C library isn’t visible to Python. Activate your conda env (conda activate prithvi) before running anything. If it persists: conda install -c conda-forge gdal --force-reinstall.

3. Loss stays flat during fine-tuning. Band-order is the most common culprit. Print your input tensor’s channel means – if they look wrong (way outside normal surface reflectance ranges), you fed the wrong bands or forgot to scale. This isn’t guaranteed to be the cause, but it’s where to look first.

4. Permission denied on git+ssh install. The pinned requirements.txt uses SSH. Fix: pip install git+https://github.com/IBM/terratorch.git, or just use the PyPI release (pip install terratorch==1.2.1).

Upgrade and cleanup

Upgrading from pre-1.2 TerraTorch is usually fine, but the model registry changed between versions. Old Prithvi-1.0 reconstruction notebooks won’t run as-is – a community thread on Hugging Face noted the latest TerraTorch made it much less simple to build the MAE model directly. Pin to an older TerraTorch or migrate to v2 backbones.

# Upgrade
pip install --upgrade terratorch

# Full cleanup
conda deactivate
conda env remove -n prithvi
rm -rf ./checkpoints/prithvi-300m-tl

No system-level artifacts, no daemons, no leftover config in ~/.config. The conda env wipes the whole stack.

FAQ

Can I run Prithvi-EO-2.0 without a GPU?

Inference on a single HLS tile – yes. Expect it to be slow (rough estimate: minutes per tile on modern CPU hardware; actual times vary). Fine-tuning without a GPU is not practical.

Does Prithvi work on raw Sentinel-2 L2A data instead of HLS?

Yes, but you handle the band reorder yourself. Sentinel-2 L2A has 12+ bands; Prithvi expects only six – Blue, Green, Red, Narrow NIR, SWIR1, SWIR2 – in that exact sequence. A rasterio script stacking B02, B03, B04, B8A, B11, B12 into a 6-channel geotiff is all you need. The arXiv paper (2412.02732) confirms the TerraTorch implementation doesn’t impose a hard limit on number of dates, so multi-temporal Sentinel-2 stacks work too. The catch: HLS applies additional atmospheric corrections and normalization that raw L2A doesn’t – your mileage may vary on out-of-distribution inputs.

What’s the difference between Prithvi-EO and Prithvi-WxC?

Different data, different use case, different repo. Prithvi-EO handles Earth observation from optical satellite imagery. Prithvi-WxC is a separate weather and climate model trained on NASA’s MERRA-2 reanalysis data. Don’t mix up the docs.

Next step: Clone github.com/blumenstiel/TerraTorch-Examples, open the multitemporal crop segmentation config, and run the fine-tune. That’s the shortest path from install to a trained model.