weathernext-download

weathernext-download downloads pretrained WeatherNext model weights, gridded WeatherNext 2 ensemble-mean forecasts, Google ARCO-ERA5 reanalysis, and paired tropical-cyclone forecast files, and provides static input fields. ERA5 reanalysis can be used to prepare model initial conditions or as reference data for forecast evaluation. Gridded downloads support year and variable selection, plus --dry-run to estimate uncompressed data sizes before downloading. Model weights come from Google's public dm_graphcast bucket by default, with CONGG/weathernext-weight available as an optional Hugging Face mirror. Static input fields are bundled with this package, with an option to fetch them from Google Cloud. WeatherNext gridded forecasts come from Google Cloud Storage, as described in Google's WeatherNext 2 model guide. ERA5 reanalysis comes from Google's public ARCO-ERA5 archive, with no login required. Cyclone products come from Google DeepMind Weather Lab.

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

Use the Hugging Face mirror instead of Google:

weathernext-download --weight wnc-25-m1 --hf

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. During a download, interactive terminals show a progress bar with the percentage, transferred size, speed, and estimated time remaining. Abbreviations are case-insensitive. Without --rename, the original weight filename is retained. --rename and --hf are available only with --weight.

Without --hf, weights are downloaded directly from Google's public bucket:

https://storage.googleapis.com/dm_graphcast/weathernext2/params/<encoded-filename>

For example, the default URL for wn2-25-m1 is:

https://storage.googleapis.com/dm_graphcast/weathernext2/params/WeatherNext2_%3C2025_model1.npz

With --hf, the Hugging Face mirror is used:

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

For example:

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.

Model input and output variables

The weights above cover three model configurations: WeatherNextCyclones, WeatherNextCyclones_Mini, and WeatherNext2. These are model tensor variables used when running the downloaded weights. A ✓ applies to all three configurations, WN2 only applies only to WeatherNext2, and — means the variable is not used in that role.

During autoregressive forecasting, predicted atmospheric and surface fields are fed back as inputs for the next time step. Static surface fields are reused, time forcings are advanced, and output-only precipitation and cyclone fields are not fed back.

Each pressure-level variable spans these 13 pressure levels, in hPa:

50, 100, 150, 200, 250, 300, 400, 500, 600, 700, 850, 925, 1000

Surface and near-surface variables have no pressure-level dimension. Heights such as 2 m, 10 m, and 100 m denote height above the surface.

Cyclone outputs are separate spatial fields, also without a pressure-level dimension. All three model configurations predict them; none use them as configured inputs.

The brace notation represents four separate quadrant variables: northeast, southeast, southwest, and northwest.

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.

Static files

--static copies static NetCDF fields bundled with the package itself, rather than downloading them over the network. These correspond to the static surface inputs listed among the model inputs above: zs (zs.nc, surface geopotential, used as terrain elevation) and lsm (lsm.nc, land-sea mask).

weathernext-download --static zs
weathernext-download --static lsm
weathernext-download --static all

--static requires a NAME. Passing all copies every bundled static file (currently zs.nc and lsm.nc); passing a specific name copies just that file. Files are copied to the current directory. An existing non-empty file with the same name is skipped rather than overwritten. --rename, --hf, and the cyclone options cannot be used with --static.

Add --gcloud to fetch the field fresh from Google Cloud instead of copying the bundled copy:

weathernext-download --static zs --gcloud
weathernext-download --static all --gcloud

--gcloud requires --static and re-extracts the requested field(s) from the public ARCO-ERA5 Zarr archive (gs://gcp-public-data-arco-era5/ar/full_37-1h-0p25deg-chunk-1.zarr-v3), using an anonymous GCS connection (no Google account required). Since zs and lsm are time-invariant fields, a single reference time is read and the time dimension is dropped. Using --gcloud requires xarray, zarr, gcsfs, and netCDF4 in your Python environment; these libraries are not installed by this package and must be provided separately.

Gridded forecasts (ensemble mean)

--gridded downloads WeatherNext 2 ensemble-mean forecasts only, saved as Zarr. These fields are averages across 64 ensemble members; this mode does not download individual members. No additional ensemble-selection flag is needed.

Using --gridded requires xarray, dask (with array support), zarr, and gcsfs in your Python environment. These libraries are not installed by this package and must be provided separately. Cyclone and weight downloads do not require them.

WeatherNext 2 provides experimental global medium-range ensemble forecasts at 0.25° resolution, initialized at 00, 06, 12, and 18 UTC, with six-hour forecast steps out to 15 days. See Google's WeatherNext 2 model guide. The ensemble-mean source is:

gs://weathernext/weathernext_2_0_0_mean/zarr/<year>_to_<next-year>/predictions.zarr

Downloading these gridded data requires a Google account approved for WeatherNext data access. If your account has not been approved, complete the WeatherNext Data Request form and wait for Google's approval. Configure your local Google Cloud credentials using the approved account before running --gridded. --gridded supports only the 2022_to_2023, 2023_to_2024, and 2024_to_2025 datasets, selected with --year 2022, --year 2023, and --year 2024, respectively.

weathernext-download --gridded --year 2022 --var sst
weathernext-download --gridded --year 2022,2023 --var sst,msl
weathernext-download --gridded --var z300,z500,u10,v10

--var is required. --year 2022 selects 2022_to_2023, and --year 2022,2023 selects that period plus 2023_to_2024. Omitting --year selects all three periods: 2022_to_2023, 2023_to_2024, and 2024_to_2025. Only starting years 2022, 2023, and 2024 are supported.

Pressure-level variables require a level suffix in hPa: 50, 100, 150, 200, 250, 300, 400, 500, 600, 700, 850, 925, or 1000. For example, z300 is valid but z is not. Levels are selected by coordinate value, not array index. No unit conversion is performed.

Each variable is saved under its own <var>_zarr directory, with one Zarr store per period inside it, such as ./sst_zarr/sst_2022_to_2023.zarr. Use --output-dir to change the root that <var>_zarr directories are created under. All times, forecast steps, and grid points in the chosen stores are retained. Pressure-level output variables are named, for example, geopotential_300hPa. Existing destinations are skipped. Writes first use a .zarr.part directory; failed partial outputs are retained and must be moved aside before retrying. This mode does not resume partial downloads or provide NetCDF output. Failures produce a nonzero exit status. A Dask progress bar displays writing progress.

Google ARCO-ERA5 reanalysis

Add --era5 to select the public ARCO-ERA5 archive instead of WeatherNext:

pip install xarray "dask[array]" zarr gcsfs
weathernext-download --gridded --era5 --year 2020 --var sst
weathernext-download --gridded --era5 --year 2019,2020 --var sst,msl,z500 --output-dir ./data

The source is gs://gcp-public-data-arco-era5/ar/full_37-1h-0p25deg-chunk-1.zarr-v3. Access is anonymous; no Google account or credentials are required. --year is required for ERA5 and selects calendar years, from 1940 onward, subject to available data. Downloads are clipped to the archive's valid_time_start and valid_time_stop metadata (validated ERA5 coverage, excluding preliminary ERA5T). The actual time range is printed; a partially available year downloads only its available hours, and an unavailable year fails.

The same surface aliases and pressure-variable prefixes listed above work. For ERA5, tp selects the source total_precipitation field, without conversion or six-hour aggregation. Pressure variables accept all 37 ERA5 levels: 1, 2, 3, 5, 7, 10, 20, 30, 50, 70, 100, 125, 150, 175, 200, 225, 250, 300, 350, 400, 450, 500, 550, 600, 650, 700, 750, 775, 800, 825, 850, 875, 900, 925, 950, 975, 1000 hPa. For example, use t975 or z500.

Output is one Zarr store per variable and year, such as ./sst_zarr/sst_era5_2020.zarr, keeping ERA5 separate from WeatherNext files. All available hourly samples and global grid points are retained. Existing outputs are skipped; .zarr.part outputs must be moved aside before retrying. Full-year global downloads can be large. No date or geographic subsetting, unit conversion, or NetCDF output is performed.

See the ARCO-ERA5 documentation for archive details. Without --era5, --gridded retains its WeatherNext behavior.

Preview download size (dry run)

Use --dry-run with either gridded source:

weathernext-download --gridded --era5 --year 2020 --var sst,msl --dry-run
weathernext-download --gridded --year 2022 --var sst,z500 --dry-run

The command reports each pending output's uncompressed selected array size (including coordinates) and the total in bytes and binary units. It reads remote metadata and coordinates but does not download field data, create output directories, or write files. Existing destinations are skipped and excluded from the total. Partial outputs and unavailable selections are reported as failures; a total with failures is explicitly marked incomplete.

This is a planning estimate, not an exact compressed download or disk size. Compression and source chunk layout affect the actual transfer; for example, reading one pressure level may require fetching chunks containing other levels. WeatherNext access credentials are still required; ERA5 remains anonymous. --dry-run requires --gridded.

Gridded data storage sizes

Gridded forecasts require substantial disk space even for one variable and one period. The following local Zarr sizes were measured with du -sh for the 2022_to_2023 dataset using the standalone reference scripts:

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.

The member count applies to the full-ensemble product selected with --ensemble. The --ensemble_mean product contains the corresponding ensemble-mean tracks, and --both downloads both products.

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