Registry / devops / hydra-core

hydra-core

JSON →
library1.3.5pypypi✓ verified 24d ago

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.

pip install hydra-core --upgrade
INSTALL
IMPORT
SIG · HYDRA-CORE
H
hydra-core
devopspythonv1.3.5
Install
3.0s avg
Import
538ms
Disk
24MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.3.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.554s · 25.7MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 3.0s · import 0.522s · 27MB
24MB installed
● package 24MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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')
hydra --version
Debug
Known issues
breakingHydra 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`.
affects: >=1.3.2
breakingThe 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.
affects: >=1.1.0
breakingHydra 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.
affects: >=1.1.0
gotchaThe `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.
affects: All
gotchaWhen `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`.
affects: All
gotchaHydra 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.
affects: All
Upgrade
Version history
1.3.5latest on PyPI · released Aug 5, 2026
Audit
Dependencies
omegaconfrequiredCore configuration object (DictConfig, OmegaConf) and resolution engine.
antlr4-python3-runtimerequiredUsed for parsing configuration overrides.
packagingrequiredUsed for version comparisons and dependency management.
importlib-resourcesrequiredUsed for accessing package data (e.g., default configs).
Agent activity
21 hits · last 30 days
node
18
OpenAI (training)
1
Resources
hydra-core — pip install hydra-core · libregistry