# Earth2studio Install

> Guide installing Earth2Studio via uv or pip, selecting model extras, and configuring the environment. Do NOT use for writing inference code, choosing models, or PhysicsNeMo questions.

- Skill: `nvidia/earth2studio-install-3` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add nvidia/earth2studio-install-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nvidia/earth2studio-install-3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- License: Apache-2.0
- Author: NVIDIA (https://skillmd.com/u/nvidia)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/nvidia/earth2studio-install-3

---


# Earth2Studio Installation Skill

## Never install packages automatically

You **MUST NOT** install, upgrade, or modify packages on the user's
behalf. Provide the exact command; the user runs it. No exceptions.

**Forbidden:** running `pip install`, `uv pip install`, `uv add`,
`uv sync`, `conda install`, `apt install`, or any package manager.

**Instead:** give the exact command and ask the user to run it.
Explain why the package is needed.

When a package is needed:

1. Identify it
2. Provide the exact command
3. Explain why it is needed
4. **Wait for the user to confirm they ran it**

Even if the user says "just install it", give the command and require
them to execute it themselves.

## Purpose

Help users install Earth2Studio and its optional model dependencies correctly for
their use case. This skill handles package installation, optional-extra selection,
environment variable configuration, and install verification.

## Prerequisites

- Python 3.10+ (3.13 recommended)
- CUDA-capable GPU with compatible drivers for GPU extras
- uv (recommended) or pip package manager
- Internet access (packages installed from PyPI and GitHub)

You are helping a user install Earth2Studio and its optional model
dependencies. Your only job is to get the package installed correctly
for their use case — do not write inference code, do not compose
workflows.

## Core principle: docs are the source of truth

Earth2Studio installation commands, version tags, and extra names change
between releases. **Before executing or recommending any install command,
fetch the live installation docs:**

```text
https://nvidia.github.io/earth2studio/main/userguide/about/install/
```

Parse the page for the current version tag, available extras, and any
special build notes. The workflow below is structural guidance — the
specific commands come from the live page.

**Local fallback:** if WebFetch is unavailable or the live page does not
render fully (e.g. JavaScript widget), read the install configuration
file in the repository instead:

```text
docs/userguide/about/install_options.yml
```

This YAML file is the single source of truth used to generate the
install page. It contains the current release tag, every optional extra
grouped by category (prognostic, diagnostic, data-assimilation, data,
perturbation, statistics, utils), per-extra preinstall steps, warnings,
and command templates for both uv and pip.

## Instructions

### Step 1. Fetch live docs

Use WebFetch on the install URL above. Extract:

- Current release version tag (e.g. `@0.18.0`)
- Available optional extras by category
- Known build quirks (e.g. `--no-build-isolation` for pip,
  manual pre-installs)

If the live page is incomplete or unavailable, read
`docs/userguide/about/install_options.yml` from the repository to
obtain the same information.

Keep this data in working memory for all subsequent steps.

### Step 2. Understand the user's environment

Ask (cap at 3 questions, skip what the user already answered):

1. **Package manager** — uv (recommended) or pip? If unsure, recommend
   uv and link <https://docs.astral.sh/uv/getting-started/installation/>
2. **Project context** — new project or adding to existing?
3. **Python version** — recommend the version from the docs
   (currently 3.13)

### Step 3. Base install

Provide commands from the live docs based on their answers:

- **uv** uses a git source (not PyPI) to handle URL-based transitive dependencies
- **pip** installs from PyPI but some extras require manual pre-install steps

After the user runs the install, verify:

```python
import earth2studio
earth2studio.__version__
```

### Step 4. Select models and extras

Present the available extras organized by use case. Ask what the user
plans to do — don't dump all options unprompted. Categories from the
docs:

| Category | Example extras |
|----------|---------------|
| Prognostic (forecasting) | ace2, aifs, aifs2, atlas, aurora, dlesym, dlwp, fcn, fcn3, fengwu, fuxi, gencast, graphcast, pangu, samudrace, sfno, stormcast, stormcast-conus, stormscope, ucast, ... |
| Diagnostic (post-processing) | cbottle, climatenet, corrdiff, cosmo, cyclone, derived, orbit, precip-afno, solarradiation-afno, windgust-afno, ... |
| Data assimilation (beta) | da-cosmo, da-healda, da-interp, da-stormcast |
| Submodules | data, perturbation, statistics, utils |

The exact list comes from the live docs — cite those, not this table.

Ask:

1. Which models do you plan to use?
2. Do you need submodule extras (data sources, perturbation methods,
   statistics)?
3. Or install everything? (uv only: `--extra all`)

### Step 5. Install selected extras

Provide the exact commands from the live docs for their selections.
Key warnings to surface:

- **Slow builds**: flash-attention (AIFS variants), natten
  (Atlas, StormCast-CONUS, StormScope, CorrDiff COSMO), torch-harmonics
  CUDA extensions (FCN3, SFNO) — can take 10-30+ minutes
- **pip-specific manual steps**: some models require
  `--no-build-isolation` or pre-installing packages like earth2grid,
  torch-harmonics, or makani
- **Data assimilation models**: require CuPy (+ cuDF for most; `da-cosmo` is
  CuPy-only), defaulting to CUDA 13 (`cupy-cuda13x`, `cudf-cu13`)

### Step 6. Configuration (offer, don't force)

Mention environment variables the user might want to set — only if
relevant (e.g. limited disk, shared filesystem, CI environment):

| Variable | Purpose |
|----------|---------|
| `EARTH2STUDIO_CACHE` | General cache directory |
| `EARTH2STUDIO_DATA_CACHE` | Data source cache (overrides general) |
| `EARTH2STUDIO_MODEL_CACHE` | Model checkpoint cache (overrides general) |
| `EARTH2STUDIO_PACKAGE_TIMEOUT` | Max seconds for model downloads |

## Troubleshooting

If installation fails, point the user to:

- <https://nvidia.github.io/earth2studio/main/userguide/support/troubleshooting/>
- <https://nvidia.github.io/earth2studio/main/userguide/support/faq/>

Common issues:

- **PyTorch/CUDA mismatch**: verify `torch.cuda.is_available()` first
- **flash-attention build failure**: CUDA toolkit version must match
  PyTorch CUDA
- **ONNX Runtime GPU**: may need version-specific install for their CUDA
- **ecCodes missing**: required for GRIB data handling; install via
  `sudo apt-get install libeccodes-dev` (Debian/Ubuntu) or
  `conda install -c conda-forge eccodes`
- **Python.h: No such file or directory**: missing Python development
  headers; install via `sudo apt-get install python3-dev`

## Limitations

- Cannot help with runtime errors unrelated to missing dependencies
- Does not cover model checkpoint downloads (those happen at first inference)
- Data source setup beyond the `data` extra is out of scope
- Cannot write inference or training code, or compose Earth2Studio workflows

## Ownership and out-of-scope

**Owns:** package installation, optional-extra selection, environment
variable configuration, install verification.

**Does not own:** writing inference or training code, composing
Earth2Studio workflows, data source setup beyond the `data` extra,
model checkpoint downloads (those happen at runtime), troubleshooting
runtime errors unrelated to missing dependencies.