Herbie: Download Weather Forecast Model Data in Python 🏁

Access HRRR, GFS, RAP, GEFS, IFS and more!

📚 Documentation | 💬 Discussions | ❔ Get Help

See also the DeepWiki generated docs.

What is Herbie?

Herbie is a Python package that makes downloading and working with numerical weather prediction (NWP) model data simple and fast. Whether you're a researcher, meteorologist, data scientist, or weather enthusiast, Herbie provides easy access to forecast data from NOAA, ECMWF, and other sources.

Key Features:

• 🌐 Access 15+ weather models - HRRR, GFS, RAP, GEFS, ECMWF, and more
• ⚡ Smart downloads - Get full GRIB2 files or subset by variable to save time and bandwidth
• 🔄 Multiple data sources - Automatically searches different archive (AWS, Google Cloud, NOMADS, Azure)
• 📊 Built-in data reading - Load data directly into xarray for analysis
• 🛠️ CLI and Python API - Use from command line or in your Python scripts
• 🗺️ Visualization aids - Includes Cartopy integration for mapping

Keywords: weather data download, GRIB2, python, numerical weather prediction, meteorological data, weather forecast API, xarray, atmospheric data, research, academia, data science, machine learning,visualization

Quick Start

Installation

With conda or mamba:

conda install -c conda-forge herbie-data

mamba install -c conda-forge herbie-data

With pip:

pip install herbie-data

With uv:

uv add herbie-data

Note: optional features require manual installation of wgrib2

Simple Example

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
)

# Show file contents
H.inventory()

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

Command Line Interface

# 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

Supported Weather Models

Herbie provides access to a wide range of numerical weather prediction models:

US Models (NOAA)

Regional

• HRRR - High Resolution Rapid Refresh (3km resolution)
• HRRR-Alaska - Alaska version
• RAP - Rapid Refresh
• NAM - North American Mesoscale Model
• NBM - National Blend of Models
• RTMA/URMA - Real-Time/Un-Restricted Mesoscale Analysis
• RRFS - Rapid Refresh Forecast System (prototype)
• HAFS - Hurricane Analysis and Forecast System

Global

• GFS - Global Forecast System
• GEFS - Global Ensemble Forecast System
• AIGFS - AI Emulator of Global Forecast System
• AIGEFS - AI Emulator of Global Ensemble Forecast System
• HGEFS - Hybrid Global Ensemble Forecast System
• CFS - Climate Forecast System

Much of this data is made available through the NOAA Open Data Dissemination (NODD) program.

Other Models

• ECMWF - IFS - ECMWF's Integrated Forecast System
• ECMWF - AIFS - ECMWF's Artificial Intelligence Forecast System
• HRDPS - Canada's High Resolution Deterministic Prediction System (Canada)
• NAVGEM - U.S. Navy Global Environmental Model

View all models in the gallery →

Core Capabilities

Features:

• 🔍 Search model output from different data sources
• ⬇️ Download full or subset GRIB2 files
• 📖 Read data with xarray and index files with Pandas
• 🗺️ Built-in Cartopy aids for mapping
• 🎯 Extract data at specific points
• 🔌 Extensible with custom model templates

  graph TD;
      d1[(HRRR)] -..-> H
      d2[(RAP)] -.-> H
      d3[(GFS)] -..-> H
      d33[(GEFS)] -.-> H
      d4[(IFS)] -..-> H
      d44[(AIFS)] -..-> H
      d5[(NBM)] -.-> H
      d6[(RRFS)] -..-> H
      d7[(RTMA)] -.-> H
      d8[(URMA)] -..-> H
      H((Herbie))
      H --- .inventory
      H --- .download
      H --- .xarray

      style H fill:#d8c89d,stroke:#0c3576,stroke-width:4px,color:#000000

Python API

Herbie's Python API is used like this:

from herbie import Herbie

# Herbie object for the HRRR model 6-hr surface forecast product
H = Herbie(
  '2021-01-01 12:00',
  model='hrrr',
  product='sfc',
  fxx=6
)

# View all variables in a file
H.inventory()

# Download options
H.download()              # Download full GRIB2 file
H.download(":500 mb")     # Download subset (all 500 mb fields)
H.download(":TMP:2 m")    # Download specific variable

# Read data into xarray
ds = H.xarray("TMP:2 m")  # 2-meter temperature
ds = H.xarray(":500 mb")  # All 500 mb level data

Command Line Interface

Herbie also has a command line interface (CLI) so you can use Herbie right in your terminal.

# Get the URL for a HRRR surface file from today at 12Z
herbie data -m hrrr --product sfc -d "2023-03-15 12:00" -f 0

# Download GFS 0.25° forecast hour 24 temperature at 850mb
herbie download -m gfs --product 0p25 -d 2023-03-15T00:00 -f 24 --subset ":TMP:850 mb:"

# View all available variables in a RAP model run
herbie inventory -m rap -d 2023031512 -f 0

# Download multiple forecast hours for a date range
herbie download -m hrrr -d 2023-03-15T00:00 2023-03-15T06:00 -f 1 3 6 --subset ":UGRD:10 m:"

# Specify custom source priority (check only Google)
herbie data -m hrrr -d 2023-03-15 -f 0 -p google

Data Sources

Herbie automatically searches for data at multiple data sources:

• NOMADS
• NOAA Open Data Dissemination Program (NODD) partners (i.e., AWS, Google, Azure).
• ECMWF Open Data Forecasts
• University of Utah CHPC Pando archive
• Local file system

Documentation & Help

📘 Full Documentation - Comprehensive guides and API reference

🖼️ Example Gallery - Browse code examples for each model

💬 GitHub Discussions - Ask questions and share ideas

🚑 Report Issues - Found a bug? Let us know

Citation & Acknowledgment

If Herbie played an important role in your work, please tell us about it!

Suggested Citation

Blaylock, B. K. (YEAR). Herbie: Retrieve Numerical Weather Prediction Model Data (Version 20xx.x.x) [Computer software]. https://doi.org/10.5281/zenodo.4567540

Suggested Acknowledgment

A portion of this work used code generously provided by Brian Blaylock's Herbie python package (https://doi.org/10.5281/zenodo.4567540)

Contributing

We welcome contributions! Here's how you can help:

• ⭐ Star this repository
• 👀 Watch for new discussions and issues
• 💬 Participate in GitHub Discussions
• 🙌 Share your work in Show and Tell
• 🐛 Report bugs or suggest features via Issues
• 📝 Improve documentation
• 🧪 Test latest releases
• 💻 Submit pull requests

Read the Contributing Guide for more details.

Project History and Background

During my PhD at the University of Utah, I created, at the time, the only publicly-accessible archive of HRRR data. Over 1,000 research scientists and professionals used that archive.

Herbie was then developed to access HRRR data from that archive and was first used on the Open Science Grid.

In 2020, the HRRR dataset was made available through the NOAA Open Data Dissemination Program. Herbie evolved from my original download scripts into a comprehensive package supporting multiple models and data sources.

Name Origin: I originally released this package under the name “HRRR-B” because it only worked with the HRRR dataset; the “B” was for Brian. Since then, I have added the ability to download many more models including RAP, GFS, ECMWF, GEFS, and RRFS with the potential to add more models in the future. Thus, this package was renamed Herbie, named after one of my favorite childhood movies.

The University of Utah MesoWest group now manages a HRRR archive in Zarr format. Maybe someday, Herbie will be able to take advantage of that archive.

About the Author

Thanks for using Herbie, and happy racing! 🏁

Brian Blaylock
🌐 Personal Webpage

Other Projects by Brian

• 🌎 GOES-2-go - Download GOES satellite data and create RGB composites
• 🌡 SynopticPy - Access mesonet data from the Synoptic API
• 🔨 Carpenter Workshop - Useful tools for meteorological data analysis
• 💬 Bubble Print - Add personality to your Python print statements
• 🌹 Pandas Rose - Easier wind rose plots
• 📜 MET Syntax - VS Code syntax highlighting for Model Evaluation Tools

Alternative Tools

rclone: As an alternative to Herbie, you can use rclone to download files from remote archives. I love rclone. Here's a short rclone tutorial.

Project Statistics