earth2studio-install

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Earth2Studio Installation Skill

Earth2Studio 安装技能

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:

Identify it
Provide the exact command
Explain why it is needed
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.

你绝对不能代表用户安装、升级或修改任何包。请提供准确的命令，由用户自行运行。无例外。

禁止操作： 执行

pip install

、

uv pip install

、

uv add

、

uv sync

、

conda install

、

apt install

或任何包管理器命令。

正确做法： 提供准确的命令并要求用户自行运行。解释安装该包的原因。

当需要安装某个包时：

明确该包的名称
提供准确的命令
解释安装该包的原因
等待用户确认已执行命令

即使用户说“直接安装它”，也要提供命令并要求他们自行执行。

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.

帮助用户根据其使用场景正确安装Earth2Studio及其可选模型依赖项。本技能负责包安装、可选附加组件选择、环境变量配置以及安装验证。

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.

Python 3.10+（推荐3.13版本）
支持CUDA的GPU及兼容驱动（用于GPU附加组件）
uv（推荐）或pip包管理器
网络连接（需从PyPI和GitHub安装包）

你需要帮助用户安装Earth2Studio及其可选模型依赖项。你的唯一任务是根据用户的使用场景正确完成包安装——请勿编写推理代码，请勿构建工作流。

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/userguide/about/install.html

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.

Earth2Studio的安装命令、版本标签和附加组件名称会随版本更新而变化。在执行或推荐任何安装命令之前，请获取最新的安装文档：

text

https://nvidia.github.io/earth2studio/userguide/about/install.html

解析该页面以获取当前版本标签、可用附加组件以及任何特殊构建说明。以下工作流程为结构性指导——具体命令请以最新页面为准。

Instructions

操作步骤

Step 1. Fetch live docs

步骤1. 获取最新文档

Use WebFetch on the install URL above. Extract:

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

Keep this data in working memory for all subsequent steps.

使用WebFetch访问上述安装URL。提取以下信息：

当前发布版本标签（例如
```
@0.14.0
```
）
按类别划分的可用可选附加组件
已知构建问题（例如pip使用
```
--no-build-isolation
```
，手动预安装依赖）

将这些信息暂存以便后续步骤使用。

Step 2. Understand the user's environment

步骤2. 了解用户环境

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

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

询问用户（最多3个问题，跳过用户已回答的内容）：

包管理器——使用uv（推荐）还是pip？若不确定，推荐uv并提供链接https://docs.astral.sh/uv/getting-started/installation/
项目场景——新建项目还是添加到现有项目？
Python版本——推荐文档中指定的版本（当前为3.13）

Step 3. Base install

步骤3. 基础安装

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__

根据用户的回答，提供最新文档中的命令：

uv 使用git源（而非PyPI）来处理基于URL的传递依赖
pip 从PyPI安装，但部分附加组件需要手动预安装步骤

用户完成安装后，通过以下命令验证：

python

import earth2studio
earth2studio.__version__

Step 4. Select models and extras

步骤4. 选择模型与附加组件

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)	aifs, aurora, graphcast, pangu, sfno, stormcast, ...
Diagnostic (post-processing)	corrdiff, climatenet, precip-afno, ...
Data assimilation (beta)	da-healda, da-interp, da-stormcast
Submodules	data, perturbation, statistics

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

Ask:

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

按使用场景整理可用附加组件并呈现给用户。询问用户的使用计划——切勿直接罗列所有选项。分类信息请参考最新文档：

类别	示例附加组件
预测（天气预报）	aifs, aurora, graphcast, pangu, sfno, stormcast, ...
诊断（后处理）	corrdiff, climatenet, precip-afno, ...
数据同化（测试版）	da-healda, da-interp, da-stormcast
子模块	data, perturbation, statistics

具体列表请以最新文档为准——引用文档内容，而非此表格。

询问用户：

你计划使用哪些模型？
是否需要子模块附加组件（数据源、扰动方法、统计工具）？
或者安装全部组件？（仅uv支持：
```
--extra all
```
）

Step 5. Install selected extras

步骤5. 安装所选附加组件

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

Slow builds: flash-attention (AIFS variants), natten (Atlas, StormScope), 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 (CUDA 12)

根据用户的选择，提供最新文档中的准确命令。需重点提示以下注意事项：

构建缓慢：flash-attention（AIFS变体）、natten（Atlas、StormScope）、torch-harmonics CUDA扩展（FCN3、SFNO）——构建可能需要10-30分钟以上
pip专属手动步骤：部分模型需要使用
```
--no-build-isolation
```
或预安装earth2grid、torch-harmonics或makani等包
数据同化模型：需要CuPy + cuDF（CUDA 12）

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

步骤6. 配置（提供选项，而非强制）

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

提及用户可能需要设置的环境变量——仅在相关场景下（例如磁盘空间有限、共享文件系统、CI环境）：

变量	用途
`EARTH2STUDIO_CACHE`	通用缓存目录
`EARTH2STUDIO_DATA_CACHE`	数据源缓存（覆盖通用缓存设置）
`EARTH2STUDIO_MODEL_CACHE`	模型 checkpoint 缓存（覆盖通用缓存设置）
`EARTH2STUDIO_PACKAGE_TIMEOUT`	模型下载最长等待时间（秒）

Troubleshooting

故障排除

If installation fails, point the user to:

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
```

若安装失败，请引导用户查看：

常见问题：

PyTorch/CUDA版本不匹配：首先验证
```
torch.cuda.is_available()
```
flash-attention构建失败：CUDA工具包版本必须与PyTorch CUDA版本匹配
ONNX Runtime GPU：可能需要针对其CUDA版本进行特定版本安装
ecCodes缺失：处理GRIB数据所需；可通过
```
sudo apt-get install libeccodes-dev
```
（Debian/Ubuntu）或
```
conda install -c conda-forge eccodes
```
安装
Python.h: No such file or directory：缺失Python开发头文件；可通过
```
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

无法帮助解决与缺失依赖无关的运行时错误
不涉及模型checkpoint下载（该操作在首次推理时进行）
超出
```
data
```
附加组件范围的数据源设置不在本技能范围内
无法编写推理或训练代码，也无法构建Earth2Studio工作流

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.

负责： 包安装、可选附加组件选择、环境变量配置、安装验证。

不负责： 编写推理或训练代码、构建Earth2Studio工作流、超出

data

附加组件范围的数据源设置、模型checkpoint下载（该操作在运行时进行）、排查与缺失依赖无关的运行时错误。