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`	模型检查点缓存（覆盖通用缓存设置）
`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: 没有该文件或目录：缺失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

无法帮助解决与缺失依赖无关的运行时错误
不涵盖模型检查点下载（该操作在首次推理时进行）
```
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

扩展包之外的数据源设置、模型检查点下载（该操作在运行时进行）、排除与缺失依赖无关的运行时错误。