For each variable, ERA5-Land (~9km grid, generally preferable for land applications) is tried first via the Copernicus Climate Data Store (CDS); if that fails for a given month (explicit CDS error, no ~/.cdsapirc configured, network issue, or a genuine coverage gap), the module automatically falls back to plain ERA5 (~31km grid, longer historical record) for that month only -- other months/ variables are unaffected. By default that fallback tier is read straight from the public ARCO-ERA5 Google Cloud archive (no CDS account needed at all for it); pass -c to use CDS's own plain-ERA5 product there instead.
One CDS quirk drives part of the ERA5-Land fallback even when ERA5-Land data actually exists: the derived-era5-land-daily-statistics product used for "instantaneous" variables (temperature, wind, pressure, ...) explicitly refuses to compute daily statistics for accumulated variables (precipitation, potential evaporation, solar radiation, snowfall). For those, t.in.era5 requests raw hourly reanalysis-era5-land data instead and sums it to a daily total itself -- still ERA5-Land, just via a different CDS product -- before falling back to the plain-ERA5 tier only if that also fails.
Requests are chunked per (variable, year, month), so a single failure doesn't force re-fetching a whole multi-year request, and repeat runs against the same cache_dir reuse already-downloaded months instead of re-downloading them.
t.in.era5 opens the store with xarray.open_zarr(..., chunks=None, storage_options=dict(token="anon")) -- matching Google's own arco-era5 usage examples for this exact dataset, and confirmed in practice to be both simpler (no dask dependency at all) and faster than chunks="auto", which only adds a dask-array layer that regroups the store's own chunks without reducing what gets transferred.
ARCO-ERA5 is an unmodified GRIB-to-Zarr conversion of the raw archive, so accumulated variables (precipitation, potential evaporation, solar radiation, snowfall) are still in ECMWF's raw forecast-accumulation form and are de-accumulated locally to daily totals, following ECMWF's published conversion guidance for these fields. This is a different correction than the one applied to ERA5-Land's raw hourly data (see above) -- do not assume the two behave the same way.
Reading ARCO-ERA5 requires the gcsfs and zarr Python packages in addition to xarray/netCDF4. make venv (see the Makefile) builds a dedicated virtualenv with all of these under the installed addon's own etc/t.in.era5/venv, which t.in.era5.py detects and uses automatically -- no manual pip install needed, and none is attempted against GRASS's own Python installation (which a plain pip install often can't touch anyway, blocked by PEP 668's externally-managed-environment guard on modern Debian/Ubuntu).
Since keeping the whole globe costs nothing beyond what a bbox-only fetch already pays for, t.in.era5 does exactly that: every ARCO-ERA5 fetch is cached permanently, at full world coverage, under arco_world_cache (default $HOME/RSDATA/ERA5World), keyed only by (variable, reduction, year, month) -- deliberately independent of area, output_prefix, or which run asked for it. The very first request for a given (variable, month) anywhere in the world pays the full download; every later request for that same (variable, month) -- for any region, any project, any future run -- is served from that local file with no network access at all. Confirmed in practice: a second fetch for a different continent's bounding box, same month, dropped from ~82s to ~0.05s. This directory grows over time by design (each cached month is a genuine, reusable slice of world coverage, compressed to a few MB per variable per month for typical fields) and is never pruned automatically -- treat it as a small, permanent local ERA5 mirror you're building up, and manage its size yourself if that ever matters. A handful of days for a brand-new month is still fast (a few minutes, paid once); only a large historical multi-month backfill of variables/months never requested before is slow, and even then only once -- for a true first-time bulk historical load, -c (CDS, which subsets server-side and so is cheaper per single request but never builds up a reusable local archive) may still be preferable.
| per variable | x 3 variables | |
|---|---|---|
| 72 months | ~4.6 GB | ~14 GB |
| 65 months (roughly what's available as of writing) | ~4.2 GB | ~13 GB |
Requesting temperature_min/temperature_max in addition to temperature adds separate cache entries each of comparable size (same underlying hourly source, but cached per daily reduction -- mean, min, max are each their own file), roughly tripling the temperature share of this estimate if all three are used.
t.in.era5 checks these on every month it fetches from ARCO-ERA5, and caches accordingly:
Accumulated fields (precipitation, potential_evaporation, solar_radiation, snowfall) are correctly de-accumulated to genuine per-hour amounts, not just relabeled daily totals split evenly -- ECMWF's raw archive stores these as running totals since a periodic reset, not as hourly increments, so getting this right means differencing consecutive raw readings and special-casing the reset hour itself (which is already a genuine 1-hour amount, not a diff). Two DIFFERENT reset schedules are involved, handled separately and correctly for each source:
| tier | hourly output | notes |
|---|---|---|
| ERA5-Land (default, tried first) | yes | via the same raw-hourly reanalysis-era5-land product the daily path already uses for accumulated variables -- in -h mode it's used for ALL variables, not just accumulated ones |
| ARCO-ERA5 (default fallback tier) | yes | genuinely hour-native at the Zarr store level; see ARCO-ERA5 SOURCE above |
| plain ERA5 via CDS (-c fallback tier, and the one-month ARCO-unavailable stopgap) | yes | via fetch_era5_raw_hourly() against CDS's raw reanalysis-era5-single-levels product (not fetch_era5()'s daily-statistics product, which has no hourly output) -- see the request-schema difference noted below |
All three source tiers now support -h.
One real, non-obvious request-schema difference found while implementing the plain-ERA5 raw-hourly fetch: unlike reanalysis-era5-land (no ensemble/product-type concept at all), reanalysis-era5-single-levels is part of the same "single-levels" product family as fetch_era5()'s derived-daily-statistics product, and CDS's schema for that family requires an explicit product_type: "reanalysis" request key (distinguishing the deterministic reanalysis from CDS's separate ensemble-member products for the same physical field). fetch_era5_raw_hourly() carries this key, mirroring fetch_era5()'s own existing single-levels request; fetch_era5land_raw_hourly() correctly does NOT, since ERA5-Land has no such family/product-type distinction to make.
Three collections are used, chosen per variable:
| variable kind | CDS collection |
|---|---|
| pressure-level (*_pl) | reanalysis-era5-pressure-levels-monthly-means |
| no ERA5-Land counterpart | reanalysis-era5-single-levels-monthly-means |
| everything else | reanalysis-era5-land-monthly-means |
All three use product_type: monthly_averaged_reanalysis. One request is issued per variable and year, not per month: the products accept a month list, a small area returns a tiny response, and CDS queues each request separately, so asking once a year rather than once a month cuts the queue wait by about twelve.
Accumulated fields (precipitation, evaporation, radiation, snowfall, snowmelt, latent heat flux) come back as the monthly mean of the daily total, which is how ECMWF publishes them — not as a monthly sum. Multiply by the number of days in the month for a monthly total.
-m requires ~/.cdsapirc: ARCO-ERA5 has no monthly product, and reducing its hourly data locally would mean transferring every hour of the period (see below).
The 37 levels ERA5 publishes are offered: 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 and 1000.
geopotential_pl is divided by standard gravity (9.80665 m/s2) and reported as geopotential height in metres, which is how the field is normally read.
| field | chunk shape | one chunk |
|---|---|---|
| pressure-level (e.g. temperature) | (1 hour, 37 levels, 721, 1440) | ~154 MB |
| single-level (e.g. mean_sea_level_pressure) | (1 hour, 721, 1440) | ~4 MB |
Neither an area subset nor a level subset reduces what must be transferred, because both are smaller than one chunk. A single hour of one pressure-level variable therefore costs about 154 MB, and any multi-year request becomes impractical — roughly 250 GB for one hour per month over 2000–2026 for five variables, for data that the CDS monthly-means product delivers, already area- and level-subset, in megabytes.
Requesting a *_pl variable without -m is therefore refused outright rather than started and left to fail.
| key | CDS variable | native units | converted to |
|---|---|---|---|
| precipitation | total_precipitation | m/day (accum.) | mm/d |
| temperature | 2m_temperature (daily mean) | K | deg C |
| temperature_min | 2m_temperature (daily min) | K | deg C |
| temperature_max | 2m_temperature (daily max) | K | deg C |
| dewpoint_temperature | 2m_dewpoint_temperature | K | deg C |
| potential_evaporation | potential_evaporation | m/day (accum.) | mm/d |
| solar_radiation | surface_solar_radiation_downwards | J/m2 (accum.) | MJ/m2/d |
| wind_u | 10m_u_component_of_wind | m/s | m/s |
| wind_v | 10m_v_component_of_wind | m/s | m/s |
| surface_pressure | surface_pressure | Pa | kPa |
| snowfall | snowfall | m (accum.) | mm/d |
| mean_sea_level_pressure | mean_sea_level_pressure | Pa | kPa |
| snow_depth | snow_depth | m w.e. | mm w.e. |
| snowmelt | snowmelt | m (accum.) | mm/d |
| latent_heat_flux | surface_latent_heat_flux | J/m2 (accum.) | MJ/m2/d |
| net_solar_radiation | surface_net_solar_radiation | J/m2 (accum.) | MJ/m2/d |
| net_thermal_radiation | surface_net_thermal_radiation | J/m2 (accum.) | MJ/m2/d |
| clear_sky_solar_radiation | surface_solar_radiation_downward_clear_sky | J/m2 (accum.) | MJ/m2/d |
| land_sea_mask | land_sea_mask | fraction | fraction |
| soil_type | soil_type | class 1-7 | class 1-7 |
| soil_water_1.._4 | volumetric_soil_water_layer_1..4 | m3/m3 | m3/m3 |
| soil_temperature_1.._4 | soil_temperature_level_1..4 | K | deg C |
Soil layers follow ERA5's four-layer scheme, shared with ERA5-Land: layer 1 is 0–7 cm, layer 2 is 7–28 cm, layer 3 is 28–100 cm and layer 4 is 100–289 cm.
mean_sea_level_pressure, land_sea_mask, soil_type and clear_sky_solar_radiation have no ERA5-Land counterpart — ERA5-Land is a land-surface rerun driven by ERA5's atmosphere — so the ERA5-Land tier is skipped for them outright rather than attempted and warned about on every chunk.
land_sea_mask and soil_type are invariant fields: they are returned for every requested timestamp, with the same values each time.
| key | CDS variable | native units | converted to |
|---|---|---|---|
| geopotential_pl | geopotential | m2/s2 | m (geopotential height) |
| temperature_pl | temperature | K | deg C |
| wind_u_pl | u_component_of_wind | m/s | m/s |
| wind_v_pl | v_component_of_wind | m/s | m/s |
| specific_humidity_pl | specific_humidity | kg/kg | g/kg |
t.in.era5 uses the cdsapi Python package, which reads credentials from ~/.cdsapirc. Create a free account at https://cds.climate.copernicus.eu, accept the ERA5/ERA5-Land dataset licences on the CDS website (one-time, per dataset), then copy your personal access token from your CDS profile page into ~/.cdsapirc:
url: https://cds.climate.copernicus.eu/api key: <your-personal-access-token>
g.region n=34 s=31 e=49 w=47 res=0:06 # ~0.1 deg, matches ERA5-Land's native grid t.in.era5 variables=precipitation,temperature,potential_evaporation \ start=2001-06-01 end=2001-08-31 \ output_prefix=karkheh cache_dir=$HOME/era5_cache r.hydro.hbv.forcing strds=karkheh_precipitation basins=basins \ basins_vector=basins_v output_table=karkheh_precip_table
t.in.era5 -h variables=precipitation start=2001-06-01 end=2001-06-07 \ output_prefix=karkheh_hourly cache_dir=$HOME/era5_cache # -> karkheh_hourly_precipitation, one raster per hour (168 maps for # this 7-day window instead of 7)
t.in.era5 -m variables=temperature,precipitation,soil_water_1,soil_temperature_1 \ start=2000-01-01 end=2020-12-31 \ output_prefix=mleiha cache_dir=$HOME/era5_cache # -> mleiha_temperature, ... one raster per calendar month (252 maps)
Pressure-level fields on the 13 levels used by biodiversity and weather foundation models, which need -m:
t.in.era5 -m \ variables=geopotential_pl,temperature_pl,wind_u_pl,wind_v_pl,specific_humidity_pl \ pressure_levels=50,100,150,200,250,300,400,500,600,700,850,925,1000 \ start=2000-01-01 end=2020-06-30 \ area=25.46,55.29,24.74,56.55 \ output_prefix=mleiha cache_dir=$HOME/era5_cache # -> 5 variables x 13 levels = 65 STRDS, named e.g. mleiha_temperature_pl_850, # each with one raster per calendar month
Available at: t.in.era5 source code (history)
Accessed: Sunday Nov 15 11:08:20 2026
Main index | Temporal index | Topics index | Keywords index | Graphical index | Full index
© 2003-2026 GRASS Development Team, GRASS 8.5.1dev Reference Manual