Herbie: downloading numerical weather prediction model data in Python

Fifteen models behind one interface

Herbie is a Python package that makes downloading and working with numerical weather prediction model data simple and fast. The stated audience is broad: researchers, meteorologists, data scientists, or anyone who wants forecast data from NOAA and ECMWF without writing the download logic themselves.

The coverage is the point. The README lists access to fifteen or more weather models, and the catalogue in the documentation runs from the US regional and global suites through the European and Canadian systems. The NOAA regional models include HRRR at 3km resolution, HRRR-Alaska, RAP, the North American Mesoscale Model, the National Blend of Models, the Real-Time and Un-Restricted Mesoscale Analyses, the Rapid Refresh Forecast System, which is marked as a prototype, and the Hurricane Analysis and Forecast System. The global NOAA models include GFS, GEFS, AIGFS, AIGEFS, HGEFS and CFS. The AI emulators of the global systems appear alongside their physical counterparts, which is a reasonable thing to see in a package that is meant to track what the agencies actually publish.

Beyond NOAA there is ECMWF's Integrated Forecast System and its Artificial Intelligence Forecast System, Canada's High Resolution Deterministic Prediction System, and NAVGEM from the US Navy.

Much of the NOAA data reaches users through the NOAA Open Data Dissemination program, which is why the archive list in the next section is a list of cloud buckets rather than a list of websites.

The design decision implied by all of this is that a user asks for a model, a time, a product and a variable, and the package figures out where the bytes live. The cost of that convenience is that you are depending on a maintained mapping between model names and archive paths, which is exactly the kind of knowledge that goes stale when an agency reorganises its buckets.

The Herbie object and the four things you tell it

The Python API is built around a single object. The README's example creates one for HRRR surface data:

from herbie import Herbie

# Create a Herbie object for HRRR model data
H = Herbie(
    '2021-01-01 12:00',  # Date and time
    model='hrrr',         # Model name
    product='sfc',        # Product type
    fxx=6                 # Forecast hour
)

Four parameters carry the request: the initialisation date and time, the model, the product and the forecast hour. The object is a description of a dataset rather than a handle on a downloaded file, and the two methods that follow make that explicit.

The inventory method lists what is inside the file, and the xarray method reads a variable:

# Show file contents
H.inventory()

# Download and read 2-meter temperature
temperature = H.xarray("TMP:2 m")

That split is a good piece of interface design. The inventory call tells you the exact variable names available for that model, product and hour, and the xarray call takes one of those names, here a short code plus a level, such as two metre temperature or temperature at 850 mb. Nothing has to be hard coded and guessed, because the naming varies between agencies and Herbie exposes the naming as data.

The forecast hour is worth understanding, since it is not the same as a valid time. `fxx=6` asks for the sixth forecast hour of that run, and `fxx=0` asks for the analysis or forecast from the initialisation itself. The CLI examples in the README use both patterns, with `-f 0` for an immediate forecast and `-f 24` for a day ahead.

Subsetting, several archives and reading into xarray

Two features do the heavy lifting for anyone working with large forecast files. The first is smart downloading, which means getting either the full GRIB2 file or a subset by variable, so you do not have to transfer a whole model run to read one field. The second is that the data arrives as an xarray object rather than a file you then have to parse.

The reading path runs through cfgrib and eccodes, and the project manifest declares both: `cfgrib>=0.9.15`, `eccodes>=2.45.0`, plus `eccodeslib>=2.44.1.8` on platforms other than win32. Around them sit numpy, pandas, pyproj for coordinate handling, requests for the transfer, and xarray for the data structure.

That dependency list is the honest answer to a question people often ask, which is what Herbie adds on top of cfgrib. It adds the parts that are not about decoding: knowing where each model's files live, knowing which archive is likely to have a given run, listing a file's contents, downloading only what you asked for, and handing the result back as an xarray dataset.

The archive search is what makes this more than a downloader. The README describes automatically searching different archives, and the project description names AWS, Google Cloud, NOMADS and Azure as the sources. The reason that matters is redundancy. Forecast data is published into several clouds, and which one has the file you want, at the resolution you want, is not something you want to encode by hand for fifteen models.

For visualisation there is Cartopy integration, and the development requirements pull in cartopy, matplotlib and metpy alongside the runtime dependencies. The package metadata classifies the intended audience as science and research, and the topic classifier as atmospheric science.

The command line for people who are not writing a script

Herbie ships a command line interface, and the README's examples show the same three ideas expressed as flags:

# Download HRRR surface forecast
herbie download -m hrrr --product sfc -d "2023-03-15 12:00" -f 0

# Get specific variable (temperature at 850 mb)
herbie download -m gfs --product 0p25 -d 2023-03-15 -f 24 --subset ":TMP:850 mb:"

# View available variables
herbie inventory -m rap -d 2023031512 -f 0

The interface is small. `download` fetches a file, `inventory` lists what is in one, `-m` selects the model, `--product` selects the product family, `-d` gives the date and time, and `-f` the forecast hour. The `--subset` argument takes the same variable expression the Python API uses, which keeps the two front ends consistent.

The `inventory` subcommand is the one worth remembering. It answers the question you always have before downloading something large, namely what is actually inside, and it does so without transferring the payload. For an unfamiliar model or product, running the inventory first is the difference between a targeted download and a multi gigabyte mistake.

Note that the date format differs between the examples. The first uses a quoted date and time string, the second uses a bare date, and the third uses the compact form `2023031512`. A parser that accepts all three is doing you a favour, but it is also a place where a typo produces a different model run rather than an error, so checking the inventory output against the run you expected is a reasonable habit.

Installing through pip, conda or uv and the wgrib2 caveat

Installation is a single command in any of the three common Python workflows. With conda or mamba:

conda install -c conda-forge herbie-data

with pip:

pip install herbie-data

or with uv:

uv add herbie-data

The package name on every index is `herbie-data`, while the import is `herbie`, which trips people up on their first attempt if they assume the two match. The project publishes to PyPI and to conda-forge, and the documentation is hosted on Read the Docs, with a separate DeepWiki set of generated docs linked from the README.

The one caveat in the installation instructions is short and easy to skim past: optional features require a manual installation of wgrib2. wgrib2 is a separate GRIB2 tool from NOAA, and Herbie can use it for some operations. That means a feature you discover in the documentation may need a binary that pip will not install for you, and on some systems that binary has its own installation prerequisites.

The Python requirement is stated in the project metadata as `>=3.11`, with classifiers for 3.11 through 3.14 and operating system classifiers for macOS, Windows and POSIX Linux. The development status classifier says Beta, which is a useful calibration for a package that is on a rapid release cadence.

The build backend is hatchling with hatch-vcs, and the version is declared as dynamic, which means the version is derived from the repository history rather than typed into the metadata by hand. The repository carries environment files for development and test, a makefile, a CI directory, a references directory and a sample_data directory, along with a CITATION.cff for citation and a HOW-TO-RELEASE.md describing the release process.

Release cadence, the beta label and where the limits are

The release history is unusually regular for a research package. Three releases in September 2026: 2026.9.0 on 2026-09-15, 2026.9.1 on 2026-09-20 and 2026.9.2 on 2026-09-27. The last push was on 2026-09-27, the same day as the latest release, and the repository is not archived. The version numbers are calendar based, which tells you that the maintainer treats this as software with a schedule rather than as an occasional script.

The licence is MIT, and the package metadata points at a Zenodo DOI for citation, which is the standard arrangement for research software that needs a citable archive of record.

There are limits to be aware of. The first is scope. Fifteen models sounds like a lot, but each model has its own product families, variable naming and archive layout, and the README's model list is a list of model names rather than a guarantee of identical feature coverage. The second is that the package is explicitly labelled Beta while shipping weekly releases, so you should pin a version in anything reproducible. The third is that Herbie sits on top of eccodes, which is a heavy native dependency, and the manifest already shows a platform carve-out for the eccodes library on Windows. Where wgrib2 is involved, that is a second native toolchain to install.

None of this makes the package a poor choice for the job it does. It makes it a choice for people who already work with GRIB data and know which model they need.

Editorial conclusion

Adopt Herbie when your work involves pulling forecast model data repeatedly across models and archives, because the multi-archive search, the inventory listing and the direct read into xarray remove the three tasks that dominate such scripts. Do not adopt it for a single one-off file where a direct URL is enough, or on Python below 3.11, since the package manifest requires 3.11 or newer. Verify first that the model and product combination you need is covered by the documentation gallery, and that the archive serving your region is reachable, then check whether the optional wgrib2 path is required for your workflow, since the README states that some optional features need it installed by hand.

Frequently asked questions

Official sources

1. blaylockbk/Herbie on GitHub
2. License: MIT
3. Project website
4. README
5. Releases