hydra Documentation

File: README.md Copy Chapter

[!IMPORTANT]
Hydra project transition: Hydra moved from the facebookresearch
GitHub organization to
hydra-ecosystem. The repository moved
with its history, issues, and pull requests intact. Hydra remains MIT-licensed.
No action is required from Hydra users at this time. Contributors should
review the current guidance in CONTRIBUTING.md. Read
Hydra's next chapter: independent stewardship
for more about the transition.

Releases Copy Section

Development

Hydra 1.4 is the current development version of Hydra.

• Hydra 1.4 is coming soon. Until the stable release is available, you can
  install Hydra from development releases on PyPI.
• Documentation
• Installation: pip install --pre --upgrade hydra-core
• Supported Python versions: 3.10 through 3.14.

Stable

Hydra 1.3 is the stable version of Hydra.

• Documentation
• Installation : pip install hydra-core --upgrade

See the NEWS.md file for a summary of recent changes to Hydra.

License Copy Section

Hydra is licensed under MIT License.

Hydra Landscape Copy Chapter

See the Hydra Landscape for
third-party libraries, templates, plugins, and projects that use or extend
Hydra.

Ask questions in GitHub Discussions or StackOverflow (Use the tag #fb-hydra or #omegaconf):

• GitHub Discussions
• StackOverflow
• X

Check out the Meta AI blog post to learn about how Hydra fits into Meta's efforts to reengineer deep learning platforms for interoperability.

Citing Hydra Copy Section

If you use Hydra in your research please use the following BibTeX entry:

@Misc{Yadan2019Hydra,
  author =       {Omry Yadan},
  title =        {Hydra - A framework for elegantly configuring complex applications},
  howpublished = {Github},
  year =         {2019},
  url =          {https://github.com/hydra-ecosystem/hydra}
}

File: ATTRIBUTION/README.md Copy Chapter

Attribution

The following sets forth attribution notices for third-party software that may be contains in portions of this software.

Namespace packages Copy Chapter

The plugins system is inspired by the 'native' example from Python Namespace Package Examples
Released under Apache license

ANTLR Copy Chapter

Hydra is using ANTLR4 for various data parsing tasks.
The ANTLR4 tool is included in the repository and in addition the packaged library contains ANTLR4 generated code.

Released under BSD and MIT licenses

File: examples/plugins/example_sweeper_plugin/README.md Copy Chapter

Hydra example Launcher plugin

This plugin provides an example for how to write a custom Sweeper for Hydra.
The provided example has a custom configuration for the sweeper that takes overrides a few parameters:

_target_: hydra_plugins.example_sweeper_plugin.example_sweeper.ExampleSweeper
# max number of jobs to run in the same batch.
max_batch_size: null
foo: 10
bar: abcde

Example app using custom sweeper:

$ python example/my_app.py -m db=mysql,postgresql
[2019-11-14 11:42:47,941][HYDRA] ExampleSweeper (foo=10, bar=abcde) sweeping
[2019-11-14 11:42:47,941][HYDRA] Sweep output dir : multirun/2019-11-14/11-42-47
[2019-11-14 11:42:47,942][HYDRA] Launching 2 jobs locally
[2019-11-14 11:42:47,942][HYDRA]        #0 : db=mysql
db:
  driver: mysql
  pass: secret
  user: omry

[2019-11-14 11:42:48,011][HYDRA]        #1 : db=postgresql
db:
  driver: postgresql
  pass: drowssap
  timeout: 10
  user: postgres_user

File: examples/plugins/example_searchpath_plugin/README.md Copy Chapter

Hydra example SearchPath plugin

This plugin provides an example for how to write a SearchPathPlugin that can manipulate the search path.
Typical use cases includes:

• A framework that wants to allow user code to discover its configurations and be able to compose with them.
• A plugin that wants to extend Hydra or another plugin by providing additional configs in existing config groups like hydra/launcher.
• A plugin that can replace the default configuration of another plugin or of Hydra itself by prepending its configurations before those that it want to replace.

SearchPath plugins are discovered and enabled automatically once they are installed.
You can use python foo.py --info to see the search path and the installed plugins.

File: examples/plugins/example_registered_plugin/README.md Copy Chapter

Hydra example plugin via `Plugins.register`

This plugin is not very useful, but it demonstrates how to register a plugin using the Plugins.register method.

File: examples/plugins/example_launcher_plugin/README.md Copy Chapter

Hydra example Launcher plugin

This plugin provides an example for how to write a custom Launcher for Hydra.
The configuration for this launcher is in packages with the plugin:

_target_: hydra_plugins.example_launcher_plugin.example_launcher.ExampleLauncher
foo: 10
bar: abcde

The example application is overriding the Launcher used by Hydra.
When the launcher is initialized, its "using" the foo and bar parameters.

Output of the example application:

$ python example/my_app.py --multirun db=postgresql,mysql
[2019-10-22 19:45:05,060] - Example Launcher(foo=10, bar=abcde) is launching 2 jobs locally
[2019-10-22 19:45:05,060] - Sweep output dir : multirun/2019-10-22/19-45-05
[2019-10-22 19:45:05,060] -     #0 : db=postgresql
db:
  driver: postgresql
  pass: drowssap
  timeout: 10
  user: postgres_user

[2019-10-22 19:45:05,135] -     #1 : db=mysql
db:
  driver: mysql
  pass: secret
  user: omry

File: examples/plugins/example_generic_plugin/README.md Copy Chapter

Hydra example plugin

this plugin is not very useful, but demonstrates the plugin discovery capability of Hydra.

Core plugins (Plugins that are developed jointly with Hydra) lives in the plugins subdirectory inside the Hydra repo.
Third party plugins can live anywhere (public or private Github repos, Organizations in-house SCM etc)

File: examples/plugins/example_configsource_plugin/README.md Copy Chapter

Hydra example config source

Use this as the template a Hydra config source plugin

Config source plugins are allowing Hydra to recognize other search path schemas in addition to the built in
file:// (which provides access to configs in the file system) and
pkg:// (which provides access to configs installed with a Python package)

This config source hard codes all the responses so it's not very useful.
Please base your tests on the data in hydra_root/tests/test_apps/config_source_test/dir.

All config sources need to pass the ConfigSourceTestSuite tests, which are expecting those specific responses.
When implementing a new config source, be sure to run it through the test suite to ensure it always behaves the same
as the other config sources.