# How to Configure Herbie Using TOML Files and Environment Variables

> Learn to configure Herbie using TOML files and environment variables. Easily customize settings without altering default files for flexible use.

- Repository: [Brian Blaylock/herbie](https://github.com/blaylockbk/herbie)
- Tags: how-to-guide
- Published: 2026-02-26

---

**Configure Herbie by editing the [`config.toml`](https://github.com/blaylockbk/herbie/blob/main/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`](https://github.com/blaylockbk/herbie/blob/main/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`](https://github.com/blaylockbk/herbie/blob/main/src/herbie/core.py)) and the `HerbieAccessor` (in [`src/herbie/accessors.py`](https://github.com/blaylockbk/herbie/blob/main/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`](https://github.com/blaylockbk/herbie/blob/main/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:

```toml

# ~/.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:

```python
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`](https://github.com/blaylockbk/herbie/blob/main/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`](https://github.com/blaylockbk/herbie/blob/main/config.toml). This override is applied after the TOML file is parsed (lines 95-100):

```python
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`](https://github.com/blaylockbk/herbie/blob/main/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:

```python
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`](https://github.com/blaylockbk/herbie/blob/main/src/herbie/__init__.py), with the `config` dictionary consumed by [`src/herbie/core.py`](https://github.com/blaylockbk/herbie/blob/main/src/herbie/core.py) and [`src/herbie/accessors.py`](https://github.com/blaylockbk/herbie/blob/main/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`](https://github.com/blaylockbk/herbie/blob/main/config.toml) file and the [`custom_template.py`](https://github.com/blaylockbk/herbie/blob/main/custom_template.py) placeholder using the built-in `default_toml` string defined in [`src/herbie/__init__.py`](https://github.com/blaylockbk/herbie/blob/main/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.