{"library":"hydra-core","title":"Hydra","description":"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.","status":"active","version":"1.3.2","language":"en","source_language":"en","source_url":"https://github.com/facebookresearch/hydra","tags":["configuration","CLI","research","ML","omegaconf","experiments"],"install":[{"cmd":"pip install hydra-core --upgrade","lang":"bash","label":"Install or Upgrade"}],"dependencies":[{"reason":"Core configuration object (DictConfig, OmegaConf) and resolution engine.","package":"omegaconf","optional":false},{"reason":"Used for parsing configuration overrides.","package":"antlr4-python3-runtime","optional":false},{"reason":"Used for version comparisons and dependency management.","package":"packaging","optional":false},{"reason":"Used for accessing package data (e.g., default configs).","package":"importlib-resources","optional":false}],"imports":[{"note":"Main module for the @hydra.main decorator.","symbol":"hydra","correct":"import hydra"},{"note":"Essential for type-hinting and interacting with the configuration object.","symbol":"DictConfig, OmegaConf","correct":"from omegaconf import DictConfig, OmegaConf"},{"note":"Function to dynamically create objects from config. Often aliased as `build`.","symbol":"instantiate","correct":"from hydra.utils import instantiate"},{"note":"Used to retrieve the original working directory when Hydra changes the CWD for a job.","symbol":"get_original_cwd","correct":"from hydra.utils import get_original_cwd"},{"note":"Provides access to Hydra's internal configuration and runtime details.","symbol":"HydraConfig","correct":"from hydra.core.hydra_config import HydraConfig"}],"quickstart":{"code":"import hydra\nfrom omegaconf import DictConfig, OmegaConf\nimport os\n\n# Create a config directory and file (e.g., conf/config.yaml)\n# In a real project, this would be a file on disk.\n# For this example, we simulate it.\n# Make sure to run `mkdir -p conf` first if running directly.\nconfig_content = \"\"\"\napp:\n  name: MyHydraApp\n  version: 1.0.0\ndb:\n  driver: mysql\n  user: ${oc.env:DB_USER, omry}\n  password: ${oc.env:DB_PASSWORD, secret}\n\"\"\"\n\n# Create a dummy config file for the quickstart to be runnable\n# In a typical setup, 'conf/config.yaml' would exist beforehand.\nif not os.path.exists('conf'):\n    os.makedirs('conf')\nwith open('conf/config.yaml', 'w') as f:\n    f.write(config_content)\n\n@hydra.main(version_base=\"1.3\", config_path=\"conf\", config_name=\"config\")\ndef my_app(cfg: DictConfig) -> None:\n    print(f\"Application Name: {cfg.app.name}\")\n    print(f\"Database Driver: {cfg.db.driver}\")\n    print(f\"Database User: {cfg.db.user}\")\n    print(f\"Database Password: {cfg.db.password}\")\n    print(f\"Original Working Directory: {hydra.utils.get_original_cwd()}\")\n    print(f\"Current Working Directory: {os.getcwd()}\")\n    print(OmegaConf.to_yaml(cfg))\n\nif __name__ == \"__main__\":\n    # Set environment variables for demonstration if not already set\n    os.environ['DB_USER'] = os.environ.get('DB_USER', 'my_db_user')\n    os.environ['DB_PASSWORD'] = os.environ.get('DB_PASSWORD', 'my_db_pass')\n    my_app()\n\n    # Clean up the dummy config file for repeated runs\n    os.remove('conf/config.yaml')\n    os.rmdir('conf')\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade your Python environment to 3.7 or newer, or pin your `hydra-core` dependency to `<1.3.2`.","message":"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.","severity":"breaking","affected_versions":">=1.3.2"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.1.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=1.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-06T00:00:00.000Z","next_check":"2026-07-05T00:00:00.000Z"}