A small command-line tool for downloading a focused set of ERA5-Land climate variables from the Copernicus Climate Data Store (CDS) API.
The tool wraps two practical download workflows:
daily: daily outputs built from daily statistics for regular variables plus daily accumulated values for accumulated variables.hourly: hourly outputs, downloaded as one request and one file per variable.
This is intentionally a CLI first, not a general-purpose Python SDK for the CDS API.
Before downloading data, configure your CDS API credentials in ~/.cdsapirc:
url: https://cds.climate.copernicus.eu/api
key: <PERSONAL-ACCESS-TOKEN>On Linux or macOS, you can create it from the shell without printing the token:
printf "CDS Personal Access Token: "
stty -echo
IFS= read -r CDS_TOKEN
stty echo
printf "\n"
printf "url: https://cds.climate.copernicus.eu/api\nkey: %s\n" "$CDS_TOKEN" > ~/.cdsapirc
chmod 600 ~/.cdsapirc
unset CDS_TOKENYou must also accept the terms of use for each CDS dataset in the CDS portal before requesting data.
During development, run the CLI from the project environment:
uv run cds-downloader daily --year 2025 --months 10To install it as a local tool from this repository:
uv tool install .After that, the command is available outside the project directory:
cds-downloader daily --year 2025 --months 10 11 12To install the latest stable tagged version from GitHub:
uv tool install git+https://github.com/reginalexavier/cds-downloader.git@v0.2.0To install the latest development version from the default branch:
uv tool install git+https://github.com/reginalexavier/cds-downloader.gitFor one-off usage without permanent installation, pin a released version when you want reproducible behavior:
uvx --from git+https://github.com/reginalexavier/cds-downloader.git@v0.2.0 cds-downloader daily --year 2025 --months 10Or run the latest development version:
uvx --from git+https://github.com/reginalexavier/cds-downloader.git cds-downloader daily --year 2025 --months 10If the installed command is not available in your shell, run:
uv tool update-shellThen reopen the terminal.
Daily workflow, with four variables handled by daily statistics and two accumulated variables:
cds-downloader daily --year 2025 --months 10 11 12By default, the daily workflow uses variable-specific statistics:
| Variable | Default statistics |
|---|---|
2m_dewpoint_temperature |
daily_minimum, daily_maximum |
2m_temperature |
daily_minimum, daily_maximum |
10m_u_component_of_wind |
daily_mean |
10m_v_component_of_wind |
daily_mean |
Accumulated variables use 00:00 by default. To override the daily statistics for the selected daily-statistics variables:
cds-downloader daily --year 2025 --months 10 --daily-statistics daily_mean daily_minimum daily_maximumTo download only one daily-statistics variable, disable the accumulated-variable subworkflow:
cds-downloader daily --year 2025 --months 10 --daily-variables 2m_temperature --no-accumulated-variablesTo download only one accumulated variable, disable the daily-statistics subworkflow:
cds-downloader daily --year 2025 --months 10 --no-daily-variables --accumulated-variables total_precipitationThis is the recommended way to download daily precipitation totals from ERA5-Land. For accumulated variables, the value timestamped at YYYY-MM-DD 00:00 represents the accumulation over the previous day. If you need strict calendar-day labels or exact calendar-month precipitation totals, account for this one-day timestamp shift when selecting and interpreting the output.
To change the timestamp used for accumulated variables:
cds-downloader daily --year 2025 --months 10 --accumulated-time 00:00Hourly workflow, with one request and one output file per variable:
cds-downloader hourly --year 2025 --months 10 11 12Validate requests without calling the CDS API:
cds-downloader daily --year 2025 --months 10 --dry-run
cds-downloader hourly --year 2025 --months 10 --dry-runFiles are written to data/ by default. Use --output-dir downloads or an absolute path to choose another destination.
Use --max-workers to run independent requests in parallel. The default is --max-workers 1, meaning sequential downloads. Low values such as 2 or 3 are usually safer; high values can increase queueing, slowdowns, or CDS rate-limit failures.
By default, requests use the bounding box from the original workflow:
north=-15.36 west=-55.91 south=-17.24 east=-53.14
Use --area to request another spatial subset. The order follows the CDS API convention: north west south east.
cds-downloader daily --year 2025 --months 10 --area -15.36 -55.91 -17.24 -53.14
cds-downloader hourly --year 2025 --months 10 --area -14.22 -57.52 -18.02 -53.62CDS provides many variables. This CLI focuses on the small set used by the original workflows:
| Workflow | Dataset | Variable | Handling |
|---|---|---|---|
daily |
derived-era5-land-daily-statistics |
2m_dewpoint_temperature |
Daily minimum and maximum by default |
daily |
derived-era5-land-daily-statistics |
2m_temperature |
Daily minimum and maximum by default |
daily |
derived-era5-land-daily-statistics |
10m_u_component_of_wind |
Daily statistics (daily_mean by default) |
daily |
derived-era5-land-daily-statistics |
10m_v_component_of_wind |
Daily statistics (daily_mean by default) |
daily |
reanalysis-era5-land |
surface_solar_radiation_downwards |
Accumulated value at the configured timestamp (00:00 by default) |
daily |
reanalysis-era5-land |
total_precipitation |
Accumulated value at the configured timestamp (00:00 by default) |
hourly |
reanalysis-era5-land |
All six variables above | Hourly series, one request per variable |
To request another variable that is compatible with the same dataset, use the CLI options:
cds-downloader hourly --year 2025 --months 10 --variables total_precipitation
cds-downloader daily --year 2025 --months 10 --daily-variables 2m_temperature --no-accumulated-variables
cds-downloader daily --year 2025 --months 10 --no-daily-variables --accumulated-variables total_precipitationTo make new variables part of the defaults, edit cds_downloader/config.py. Before adding a variable to the daily workflow, check the CDS dataset documentation to decide whether it belongs to derived-era5-land-daily-statistics or should be treated as an accumulated variable from reanalysis-era5-land.
The daily-statistics subworkflow uses derived-era5-land-daily-statistics. That CDS API process does not expose data_format or download_format, so those fields are not sent. For the one-variable-per-request pattern used by this CLI, cdsapi returns a NetCDF/HDF5 file, saved as .nc.
The accumulated variables in the daily workflow and the entire hourly workflow use reanalysis-era5-land, which supports --data-format (netcdf or grib) and --download-format (unarchived or zip).
Run checks locally with:
uv run ruff format --check
uv run ruff check
uv run pytestOptional pre-commit setup:
uv run task pci # install Git hooks
uv run task pcr # run hooks on all files
uv run task pcu # update hook versionsThe repository also includes a GitHub Actions workflow that runs formatting checks, linting, and tests on Linux and Windows.
This project is licensed under the MIT License. See LICENSE.
The MIT License applies only to this software. Data downloaded with this tool is provided by the Copernicus Climate Data Store and remains subject to the terms and licenses of the corresponding CDS datasets. Users are responsible for reviewing and accepting the applicable CDS dataset terms before downloading or using the data.
- CDS API setup: https://cds.climate.copernicus.eu/how-to-api
- CDS terms of use: https://cds.climate.copernicus.eu/licences/terms-of-use-cds
- CDS API process
derived-era5-land-daily-statistics: https://cds.climate.copernicus.eu/api/retrieve/v1/processes/derived-era5-land-daily-statistics - CDS API process
reanalysis-era5-land: https://cds.climate.copernicus.eu/api/retrieve/v1/processes/reanalysis-era5-land - ERA5 family post-processed daily statistics documentation: https://confluence.ecmwf.int/display/CKB/ERA5+family+post-processed+daily+statistics+documentation