Hydra

1.3.2 · active · verified Mon Apr 06

Hydra is an open-source Python framework developed by Facebook Research for elegantly configuring complex applications. It enables hierarchical configuration, command-line overrides, multi-run experiments, and dynamic object instantiation. Hydra maintains a regular release cadence with both major and patch versions to introduce new features and address bugs.

Warnings

breaking Hydra 1.3.2 dropped support for Python 3.6. Applications running on Python 3.6 will not be able to upgrade to this or newer versions of Hydra.
Fix: Upgrade your Python environment to 3.7 or newer, or pin your `hydra-core` dependency to `<1.3.2`.
breaking The default composition order of the Defaults List changed significantly in Hydra 1.1. In Hydra 1.0, configs from the defaults list would override the primary config, but in 1.1 and later, the primary config overrides configs from the defaults list. This requires explicit use of the `_self_` keyword.
Fix: To maintain previous behavior or control composition, explicitly add `_self_` to your `defaults` list. Place `_self_` at the beginning for defaults to override the primary config, or at the end for the primary config to override defaults. Refer to the official upgrade guide for details.
breaking Hydra 1.1 introduced recursive defaults lists and recursive instantiation, which changed how configurations are composed and objects are created. Upgrading from 1.0 to 1.1 requires careful review of the changes, especially regarding `OmegaConf` 2.1 compatibility.
Fix: Refer to the comprehensive 1.0 to 1.1 upgrade guide in the official Hydra documentation. It's recommended to upgrade to the latest 1.0 patch version first and address all warnings before proceeding to 1.1.
gotcha The `version_base` parameter in `@hydra.main` should be explicitly set (e.g., `version_base='1.3'` or `version_base=None`). Not setting it can lead to backward compatibility warnings or unexpected behavior in future Hydra versions.
Fix: Always specify `version_base` in `@hydra.main`. Use `version_base=None` to opt into the latest behavior, or a specific version string (e.g., `'1.1'`, `'1.2'`, `'1.3'`) to maintain behavior compatible with that version.
gotcha When `hydra.job.chdir=True` (which became `False` by default in v1.2), Hydra changes the current working directory to the job's output directory. Using `os.getcwd()` will then return this new directory, not where your script was launched. This can cause issues with relative file paths.
Fix: To reliably get the directory where your script was initially executed, use `hydra.utils.get_original_cwd()`. If you need the job's output directory, you can retrieve it from `hydra.core.hydra_config.HydraConfig.get().runtime.output_dir`.
gotcha Hydra has a tight dependency on specific versions of `OmegaConf`. Incompatible `OmegaConf` versions can lead to installation failures or runtime errors. For instance, Hydra 1.3.1 specifically relaxed its pin to allow `OmegaConf` 2.3.
Fix: Always ensure your `omegaconf` installation is compatible with your `hydra-core` version. Check the `hydra-core` PyPI page or `requirements.txt` on GitHub for the exact `omegaconf` version range. Use `pip install hydra-core --upgrade` to ensure compatible versions are installed.

Install

pip install hydra-core --upgrade Install or Upgrade

Imports

hydra
```
import hydra
```
Main module for the @hydra.main decorator.
DictConfig, OmegaConf
```
from omegaconf import DictConfig, OmegaConf
```
Essential for type-hinting and interacting with the configuration object.
instantiate
```
from hydra.utils import instantiate
```
Function to dynamically create objects from config. Often aliased as `build`.
get_original_cwd
```
from hydra.utils import get_original_cwd
```
Used to retrieve the original working directory when Hydra changes the CWD for a job.
HydraConfig
```
from hydra.core.hydra_config import HydraConfig
```
Provides access to Hydra's internal configuration and runtime details.

Quickstart

This quickstart demonstrates a basic Hydra application. It defines a configuration in `conf/config.yaml`, uses `@hydra.main` to load it, and accesses configuration values via dot notation. It also shows how to use environment variables and retrieve working directory paths.

import hydra
from omegaconf import DictConfig, OmegaConf
import os

# Create a config directory and file (e.g., conf/config.yaml)
# In a real project, this would be a file on disk.
# For this example, we simulate it.
# Make sure to run `mkdir -p conf` first if running directly.
config_content = """
app:
  name: MyHydraApp
  version: 1.0.0
db:
  driver: mysql
  user: ${oc.env:DB_USER, omry}
  password: ${oc.env:DB_PASSWORD, secret}
"""

# Create a dummy config file for the quickstart to be runnable
# In a typical setup, 'conf/config.yaml' would exist beforehand.
if not os.path.exists('conf'):
    os.makedirs('conf')
with open('conf/config.yaml', 'w') as f:
    f.write(config_content)

@hydra.main(version_base="1.3", config_path="conf", config_name="config")
def my_app(cfg: DictConfig) -> None:
    print(f"Application Name: {cfg.app.name}")
    print(f"Database Driver: {cfg.db.driver}")
    print(f"Database User: {cfg.db.user}")
    print(f"Database Password: {cfg.db.password}")
    print(f"Original Working Directory: {hydra.utils.get_original_cwd()}")
    print(f"Current Working Directory: {os.getcwd()}")
    print(OmegaConf.to_yaml(cfg))

if __name__ == "__main__":
    # Set environment variables for demonstration if not already set
    os.environ['DB_USER'] = os.environ.get('DB_USER', 'my_db_user')
    os.environ['DB_PASSWORD'] = os.environ.get('DB_PASSWORD', 'my_db_pass')
    my_app()

    # Clean up the dummy config file for repeated runs
    os.remove('conf/config.yaml')
    os.rmdir('conf')

view raw JSON →