Deploy Pangu-Weather v1.0: Install Guide [2025]

Install Huawei's Pangu-Weather v1.0 open models or ECMWF ai-models-panguweather 0.0.9. System specs, CUDA traps, verification, and real error fixes.

Taylor Kim2026-09-226 min readIntermediate

Why Pangu-Weather still surprises people in 2025

1.4 seconds. That is a full global 24-hour forecast at 0.25° on one Tesla V100 – the figure that stuck from the Nature paper (arXiv 2211.02556). Official Pangu-Weather v1.0 ships four ONNX weights to do it. Most write-ups stop at download-and-run. Below: two working install paths, the CUDA/VRAM failures that still show up on GitHub, and how to prove the session actually used the GPU.

Start with ECMWF ai-models-panguweather 0.0.9 unless you need raw ONNX session control. Official repo second. License up front: trained parameters are BY-NC-SA 4.0 – commercial use forbidden; ERA5 training also means Copernicus terms apply.

System requirements for Pangu-Weather

What actually runs, as of late 2025:

OS: Linux preferred; Windows OK
Python 3.10+ (plugin baseline; official scripts match)
RAM 16 GB+; disk ~6-8 GB for four ~1.1 GB ONNX files + assets + outputs
GPU: NVIDIA. Official path pins CUDA 11.6 + cuDNN 8.2.4 (Linux) / 8.5.0.96 (Windows). CUDA 12.x machines often list CUDAExecutionProvider then silently run CPU anyway

12 GB cards (RTX 3060-class) have OOM’d mid-forward even though each weight file is only ~1.1 GB on disk – arena defaults blow up activations. CPU-only works; a 10-day plugin run can take hours instead of roughly one minute on GPU.

Download sources (official and plugin)

Code + sample inputs: 198808xc/Pangu-Weather (v1.0 release; Feb 2023-era tag, still the open weights people use). Models:

pangu_weather_1.onnx
pangu_weather_3.onnx
pangu_weather_6.onnx
pangu_weather_24.onnx

README points at Google Drive / Baidu (~1.1 GB each). Sample input_surface.npy / input_upper.npy (2018-09-27 12 UTC ERA5) live there too.

Plugin path skips the manual hunt – assets pull on first --download-assets.

Install: ECMWF path (ai-models-panguweather 0.0.9)

GRIB/ERA5 fetch, weight download, iterative stepping – handled. Package dated 24 Sep 2024 on PyPI; needs ai-models and Python ≥3.10.

Env:

conda create -n pangu python=3.10 -y
conda activate pangu
conda install cudatoolkit
pip install ai-models
ONNXRUNTIME=onnxruntime-gpu pip install ai-models-panguweather

Drop the ONNXRUNTIME= line (or set onnxruntime) for CPU.

Assets once:

ai-models --download-assets --assets ./assets-pangu panguweather

CDS example (free CDS account + ~/.cdsapirc):
```
ai-models --input cds --date 20230920 --time 0000 --assets ./assets-pangu --lead-time 240 panguweather
```
Default path is yesterday 12Z via MARS if you have ECMWF credentials. Out: panguweather.grib (or --path). Field list: ai-models --fields panguweather. Stack docs: ecmwf-lab/ai-models.

Set export AI_MODELS_ASSETS=./assets-pangu once. Later calls stop asking where the weights went.

Install: raw official v1.0

git clone https://github.com/198808xc/Pangu-Weather.git
cd Pangu-Weather
pip install -r requirements_gpu.txt # after CUDA 11.6 + matching cuDNN
# or: pip install -r requirements_cpu.txt

requirements_gpu.txt is tiny on purpose:

numpy
onnx==1.12.0
onnxruntime-gpu==1.14.0

Drop the four .onnx files in place. Make input_data/ and output_data/. Sample npy → input_data/. Then python inference_gpu.py (or inference_cpu.py). Multi-day: python inference_iterative.py.

Copy the session flags from inference_gpu.py if you roll your own runner – arena_extend_strategy='kSameAsRequested' plus mem-arena/pattern off. Those lines exist because default ORT arenas and 12 GB cards do not get along (GitHub #63).

First-time configuration and input gotchas

Surface: shape (4, 721, 1440), order MSLP, U10, V10, T2M. Upper: (5, 13, 721, 1440) for Z, Q, T, U, V on 1000/925/850/700/600/500/400/300/250/200/150/100/50 hPa. Both float32. Height labeled as Z? Multiply by 9.80665 – the model wants geopotential. Wrong grid, missing levels, or a large bias vs ERA5-style analyses and the forecast diverges fast; community runs confirm blow-ups off-distribution.

Lead times: prefer the largest step that fits the remaining hours (24 h blocks when you can, mix 6 h) instead of stacking many short hops. Hierarchical temporal aggregation is there so autoregressive error grows slower – e.g. 6+3 beats three 3 h steps for a 9 h target (see issue #18 discussion + inference_iterative.py).

Verify the install works

import onnxruntime as ort
print(ort.get_available_providers())
sess = ort.InferenceSession("pangu_weather_24.onnx", providers=[("CUDAExecutionProvider", {}), "CPUExecutionProvider"])
print(sess.get_providers())

Second print must list CUDAExecutionProvider first. Then run sample inference and check output_upper.npy / output_surface.npy shapes. Plugin: GRIB step metadata should match --lead-time.

One short observation: watching the provider list advertise CUDA while the live session sticks to CPU – no exception, just slow – is still the failure mode I see most (GitHub #67 pattern).

Common install errors and fixes

Error / symptom	Likely cause	Fix
FileNotFoundError: pangu_weather_24.onnx	Wrong cwd or models missing	Place .onnx beside the script or use absolute paths
Providers show only CPUExecutionProvider	CUDA/cuDNN mismatch or wrong onnxruntime-gpu build	Pin CUDA 11.6 + cuDNN 8.2.4 per official README, or a CUDA-12-matched onnxruntime-gpu; reinstall with ONNXRUNTIME=onnxruntime-gpu
CUDA OOM on 12 GB	Default arena + large activations	Reuse SessionOptions + cuda_provider_options from inference_gpu.py; smaller lead or CPU
DLL load failed / onnxruntime_pybind	Windows DLL mix or CPU+GPU packages both installed	Clean env; conda-forge onnxruntime (or gpu variant)
MARS/CDS access denied	Missing credentials	–input cds + free CDS key for lagged ERA5, or –file your own GRIB

Upgrade and uninstall

Plugin: pip install -U ai-models ai-models-panguweather. Assets stay; --download-assets again only if checksums change. Official tree rarely moves – git pull, keep the pinned onnx/onnxruntime pair while it works. Cleanup: delete the env, the ~5 GB ONNX+assets tree, leftover GRIB/npy. Nothing installs as a service.

Pick a date you already care about. Run the CDS command with --lead-time 48, open the GRIB in your usual viewer or eccodes, and compare 2 m temperature to a known analysis. Does that single field look sane – or did the stack quietly degrade?

FAQ

Do I need all four ONNX models?

No. Pure 24 h jump: only pangu_weather_24.onnx. Keep 1/3/6 if you iterate multi-day.

Can I feed GFS or other non-ECMWF initial conditions?

After remap to exact 0.25° grid, variable set, level list, and float32 layout – technically yes. Accuracy drops; off-ERA5 analyses can blow up within a few steps. Stick to CDS ERA5 or ECMWF-like fields. Convert height → geopotential (×9.80665) when the source gives height.

Is there a Docker image or newer open drop-in?

No official Docker in the open v1.0 repo. Managed cloud weather products from the same lab family are separate commercial offerings – different weights, not a free upgrade path for these ONNX files. For local open work, ECMWF plugin 0.0.9 (as of Sep 2024) plus official v1.0 pins above are still the practical pair in late 2025. BY-NC-SA on the trained parameters does not go away if someone wraps them in a container.