weathernext-download

weathernext-download downloads pretrained WeatherNext model weights and paired tropical-cyclone forecast files. Cyclone products come from Google DeepMind Weather Lab; model weights are downloaded from the CONGG/weathernext-weight Hugging Face repository.

Installation

pip install --upgrade weathernext-download

Or from source:

git clone https://github.com/CongGao-CG/weathernext-download.git
cd weathernext-download
pip install .

The package has no third-party Python runtime dependencies. Both cyclone files and model weights are downloaded using Python's standard-library urllib.

Model weights

List all 18 available pretrained weights and their abbreviations:

weathernext-download --weight list

Download one weight:

weathernext-download --weight wnc-25-m1

Save it using its abbreviation (wnc-25-m1.npz) instead of its original filename:

weathernext-download --weight wnc-25-m1 --rename

Download all 18 weights:

weathernext-download --weight all

Add --rename to save all 18 files as their abbreviations:

weathernext-download --weight all --rename

Weights are stored under ./weathernext-weight. A complete existing file is skipped. A smaller partial file is resumed using an HTTP Range request. Abbreviations are case-insensitive. Without --rename, the original weight filename is retained. --rename is available only with --weight.

The files are downloaded using URLs with this form:

https://huggingface.co/CONGG/weathernext-weight/resolve/main/<encoded-filename>

For example, wn2-25-m1 uses:

https://huggingface.co/CONGG/weathernext-weight/resolve/main/WeatherNext2_%3C2025_model1.npz

Weight inventory

The combined download size is 12,219,111,988 bytes, or approximately 11.380 GiB. The year after < identifies the first evaluation year: for example, <2025 was trained on data through 2024.

Models 1–4 are independently initialized and trained checkpoints of the same architecture. They are intended to be combined as a deep ensemble; model 4 is not newer than model 1. The Mini checkpoints have only one weights file.

The model implementations and original model inventory are maintained in Google DeepMind's WeatherNext repository. The model weights are separate from this package and remain subject to their own license and terms.

Cyclone forecast products

Weather Lab provides experimental cyclone predictions paired with observed tracks for verification. Every model below is available as an ensemble mean (--ensemble_mean), a full ensemble of member tracks (--ensemble), or both (--both), in CSV (--csv) or ATCF (--atcf) format.

Coverage was checked against the Weather Lab download endpoints on 2026-09-03 and may expand or contain isolated gaps. An unavailable upstream file is reported as a failed download. See Google's Weather Lab guide for its description and terms for experimental cyclone forecast data.

Cyclone usage

All cyclone-product commands require --cyclone. Without it, cyclone options are rejected.

Download one forecast cycle:

weathernext-download --cyclone --time 2026070100 --ensemble_mean

Download both products for all four cycles on one day:

weathernext-download --cyclone --date 20260701 --both

Download a month or year:

weathernext-download --cyclone --date 202607 --both
weathernext-download --cyclone --date 2026 --both

Download ATCF files from the FNV3P2 model:

weathernext-download --cyclone --date 20220101 --v3p2 --both --atcf

Time selection

• --time YYYYMMDDHH downloads one cycle. The hour must be 00, 06, 12, or 18.
• --date YYYYMMDD downloads all four cycles on one day.
• --date YYYYMM downloads all four cycles for every day in one month.
• --date YYYY downloads all four cycles for every day in one year.
• Date selections are capped at the date obtained from current UTC time minus 24 hours and restricted to the selected model's temporal coverage. A period with no overlap exits with an error instead of sending invalid requests.
• With neither option, all cycles within the selected model's temporal coverage are downloaded through the date obtained from current UTC time minus 24 hours.

Product selection

• --ensemble_mean or --ensemble-mean
• --ensemble
• --both (default)

File format

• --csv (default)
• --atcf

Model selection

• --oper for OPER (default)
• --wnv3 for WNV3
• --v3p2 for FNV3P2
• --v3p1 for FNV3P1
• --v3p0 for FNV3P0
• --v3p2LE or --v3p2le for FNV3_LARGE_ENSEMBLE

Files are stored under ./ensemble_mean and ./ensemble in the directory where the command is run. Existing non-empty files are skipped. Each new file is first written to a temporary file and moved into place only after the download completes.

Run weathernext-download --help for all options, including timeout and retry settings. --timeout and --retries apply to both download modes.

License

MIT