How to Configure Herbie Using TOML Files and Environment Variables

Configure Herbie by editing the config.toml file in ~/.config/herbie or by setting the HERBIE_CONFIG_PATH and HERBIE_SAVE_DIR environment variables to override defaults without touching the configuration file.

Herbie, the Python package for downloading numerical weather prediction (NWP) model data from the blaylockbk/herbie repository, uses a flexible dual-layer configuration system. You can persist settings in a TOML file for permanent changes or use environment variables for temporary overrides across different computing environments.

Understanding Herbie's Configuration Architecture

All configuration logic resides in src/herbie/__init__.py, which acts as the central loader when you import herbie. On first import, Herbie checks for the existence of a TOML configuration file and creates one with sensible defaults if missing. The system then parses this file and applies any environment variable overrides, storing the final merged dictionary in the module-level config variable.

The Herbie core class (defined in src/herbie/core.py) and the HerbieAccessor (in src/herbie/accessors.py) both consume this config dictionary at runtime to determine default models, forecast hours, and save locations.

Configuring Herbie with the TOML File

Default Configuration Location

By default, Herbie stores its configuration at ~/.config/herbie/config.toml. You can change this location by setting the HERBIE_CONFIG_PATH environment variable before importing the package. The path expansion logic (lines 78-81 in src/herbie/__init__.py) uses a custom Path.expand() method to resolve variables like ${HOME} or ~.

If the configuration file does not exist when Herbie is imported, the package automatically writes a built-in default TOML string to the expected path (lines 46-73).

Structure of the config.toml File

The TOML file contains a [default] table that defines baseline behavior for all Herbie operations. The default_toml constant (defined at lines 90-99) specifies the following keys:

• model: Default weather model to query (e.g., "gfs")
• fxx: Default forecast hour as an integer (e.g., 0)
• save_dir: Directory where downloaded files are stored
• overwrite: Boolean flag to re-download existing files
• verbose: Boolean flag to control logging output

The save_dir value in the default template dynamically references the HERBIE_SAVE_DIR environment variable, falling back to ~/data if unset.

Editing the Configuration File

To permanently change Herbie's behavior, edit the TOML file directly:

# ~/.config/herbie/config.toml

[default]
model = "hrrr"
fxx = 6
save_dir = "${HOME}/weather_data"
overwrite = false
verbose = true

Changes take effect on the next Python session when import herbie reloads the configuration.

Overriding Configuration with Environment Variables

Environment variables provide a mechanism to override TOML settings without modifying files, which is essential for containerized deployments or shared computing clusters.

HERBIE_CONFIG_PATH

Set this variable to relocate the entire configuration directory. Herbie expands environment variables and tilde characters in the path using the Path.expand() helper:

import os
os.environ["HERBIE_CONFIG_PATH"] = "$HOME/.my_herbie"
import herbie  # Creates config.toml at ~/.my_herbie/config.toml

This logic is implemented at lines 78-81 in src/herbie/__init__.py.

HERBIE_SAVE_DIR

Set this variable to force a specific download directory regardless of the save_dir value in config.toml. This override is applied after the TOML file is parsed (lines 95-100):

import os
os.environ["HERBIE_SAVE_DIR"] = "/mnt/storage/herbie"
import herbie
print(herbie.config["default"]["save_dir"])

# Output: PosixPath('/mnt/storage/herbie')

This approach is ideal for temporary workflows where you want to redirect output without editing persistent configuration files.

Advanced Path Expansion with Path.expand()

Herbie injects a convenience method Path.expand() into Python's pathlib.Path class (defined at lines 49-76 in src/herbie/__init__.py). This method expands shell-style variables like ${HOME} and ${USER} as well as tilde (~) characters before any path is used.

You can leverage this helper directly in your own scripts:

from herbie import Path
custom_path = Path("$HOME/data/${USER}").expand()
print(custom_path)  # Fully expanded Path object

This expansion mechanism enables portable configuration files that work across different user accounts and operating systems without hardcoding absolute paths.

Summary

• Configuration file: Herbie automatically creates ~/.config/herbie/config.toml on first import, storing defaults under the [default] table.
• Environment variables: Set HERBIE_CONFIG_PATH to change where the TOML file lives, or HERBIE_SAVE_DIR to override the download directory temporarily.
• Path expansion: Herbie's Path.expand() method processes ${VAR} and ~ syntax in all paths, enabling dynamic, user-agnostic configuration values.
• Source location: All configuration logic resides in src/herbie/__init__.py, with the config dictionary consumed by src/herbie/core.py and src/herbie/accessors.py.

Frequently Asked Questions

Where is the Herbie configuration file located?

By default, Herbie stores its configuration at ~/.config/herbie/config.toml. You can change this location by setting the HERBIE_CONFIG_PATH environment variable before importing the package. If the file does not exist, Herbie automatically creates it with default values during the first import.

Can I use environment variables inside the TOML file?

Yes. Herbie's custom Path.expand() method processes shell-style variable syntax such as ${HOME} or ${USER} within path strings. This allows you to write portable configuration entries like save_dir = "${HOME}/weather_data" that resolve correctly across different systems and user accounts.

How do I reset Herbie to default configuration?

To reset Herbie to factory defaults, delete the configuration directory (default: ~/.config/herbie). The next time you import herbie, the package will detect the missing directory and recreate both the config.toml file and the custom_template.py placeholder using the built-in default_toml string defined in src/herbie/__init__.py.

Does Herbie support multiple configuration profiles?

The built-in configuration system uses a single [default] table in the TOML file. However, you can simulate multiple profiles by maintaining separate configuration directories and switching between them using the HERBIE_CONFIG_PATH environment variable. For programmatic profile switching within a single session, you can directly manipulate the herbie.config dictionary after import.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}