Skip to content
Get packs

Guide · Open source

How to use Hydra: install hydra-core and configure Python apps

Updated · written with AI from the project's own documentation and checked against our catalogue data

Hydra is an open-source Python framework for configuring applications that have many settings. This guide explains what it is for, how to install the hydra-core package with pip, and where to go next to learn how configurations are written and loaded. It is written for developers who are new to the project.

Hydrahydra-ecosystem/hydra · ★ 10.7k · MIT

Quick start

  1. 1Check your Python version. Confirm you are running Python 3.10 through 3.14.
  2. 2Install hydra-core. Run the pip command for the 1.4 prerelease, or the 1.3 legacy command if you need a stable documented version.
  3. 3Read the docs. Open hydra.cc to learn how configuration is written and loaded, since the README gives few details.
  4. 4Organize your settings. Move your application's options into a structure Hydra can load, following the official guide.
  5. 5Ask for help if needed. Post questions in GitHub Discussions or on StackOverflow with the #fb-hydra tag.

What is Hydra and when should you use it?

Hydra is described as a framework for elegantly configuring complex applications. The idea is to organize settings so they can be changed without rewriting your code.

It fits best when your application has many configuration options, or when you run experiments with different settings and need to keep track of them. If your project has only a handful of settings, a simple config file or argument parser is usually enough.

  • Good fit: Python apps with many configuration options
  • Good fit: research teams running experiments with varying settings
  • Good fit: teams that want configuration managed separately from application code
  • Not needed: projects with only a few settings
  • Not suitable: non-Python projects, since the package is published as hydra-core for Python

Check the Python requirement

Hydra supports Python 3.10 through 3.14. Check your interpreter version before installing.

python --version

Install hydra-core with pip

The Python package is named hydra-core. The README lists two install options. The first installs the latest published prerelease of Hydra 1.4, which is still a release candidate and not final. The second installs the legacy 1.3 line, which is the documented stable version for users who need it.

  • Latest prerelease (1.4 release candidate): install with the --pre flag
  • Legacy 1.3 line: install a version constrained to 1.3 or later but below 1.4
pip install --pre --upgrade hydra-core pip install --upgrade "hydra-core>=1.3,<1.4"

Choose between Hydra 1.4 and Hydra 1.3

Hydra 1.4 is in the release candidate phase, and the README notes that the 1.4.0rc3 release notes and documentation are available. Hydra 1.3 is the legacy version and has its own documentation. Pick 1.3 if you need a stable, documented version and do not want to depend on a release candidate.

The project's NEWS.md file summarizes recent changes, so check it before upgrading an existing project.

  • Use 1.4 (prerelease) to try the newest release candidate
  • Use 1.3 for a stable, documented line

Learn how to write and load configuration

The README is short on detail about how configuration is written and loaded in code. For those specifics, use the official documentation at hydra.cc. The 1.4 docs are at hydra.cc/docs/intro/ and the 1.3 docs are at hydra.cc/docs/1.3/intro/.

If you get stuck, the README points to GitHub Discussions and StackOverflow, using the tags #fb-hydra or #omegaconf.

  • Official docs: hydra.cc
  • Questions: GitHub Discussions or StackOverflow

Compare Hydra with similar projects

Projects often compared with Hydra include OmegaConf, Dynaconf and Pydantic Settings. OmegaConf is closely connected to Hydra, since the README lists it as a tag for questions. Choose based on how you want to define and validate your settings, and test the candidates on a small piece of your own project first.

What people use it for

  • Organizing many training or model settings for a Python machine learning project
  • Running experiments with different settings and keeping track of which ones were used
  • Keeping configuration files separate from application code

Frequently asked questions

Is Hydra free to use?

Yes. Hydra is licensed under the MIT License, as stated in the README. The license file is linked from the repository.

How do I install Hydra?

Install the hydra-core package with pip. For the latest prerelease, run pip install --pre --upgrade hydra-core. For the legacy 1.3 line, run pip install --upgrade "hydra-core>=1.3,<1.4".

What Python version does Hydra need?

The README says Hydra supports Python 3.10 through 3.14. Check your version before installing.

Should I use Hydra 1.4 or 1.3?

Hydra 1.4 is still a release candidate and not final. If you need a stable, documented version, use the 1.3 line instead.

Can I use Hydra with a non-Python project?

No. The package is published as hydra-core for Python, so it is only relevant to Python projects.

What can I use instead of Hydra?

Comparable projects named in this guide are OmegaConf, Dynaconf and Pydantic Settings. A simple config file or argument parser can also be enough for small projects.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Hydra suits Python developers whose applications have many settings, or researchers who run experiments with varying configurations. If your project only has a few settings, a simple config file or argument parser is likely a better choice. The README is light on detail, so read the official docs before committing to it.

Install options & downloads