Skip to main content
Version: Next

Config Search Path

The Config Search Path is a list of paths that Hydra searches in order to find configs. It is similar to the Python PYTHONPATH.

  • When a config is requested, The first matching config in the search path is used.
  • Each search path element has a schema prefix such as file:// or pkg:// that corresponds to a ConfigSourcePlugin.
    • file:// points to a file system path. It can either be an absolute path or a relative path. Relative path will be resolved to absolute based on the current working dir. Path separator is / on all Operating Systems.
    • pkg:// points to an importable Python module, with . being the separator. files are needed in directories for Python to treat them as packages.

You can inspect the search path and the configurations loaded by Hydra via the --info flag:

$ python --info searchpath

There are a few ways to modify the config search path, enabling Hydra to access configuration in different locations. Use a combination of the methods described below:

Using @hydra.main()#

Using the config_path parameter @hydra.main(). The config_path is relative to location of the Python script.

Overriding hydra.searchpath config#

ย Example

In some cases you may want to add multiple locations to the search path. For example, an app may want to read the configs from an additional Python module or an additional directory on the file system.
Configure this using hydra.searchpath in your primary config or your command line.


hydra.searchpath can only be configured in the primary config. Attempting to configure it in other configs will result in an error.

In this example, we add a second config directory - additional_conf, next to the first config directory:

โ”œโ”€โ”€ __init__.pyโ”œโ”€โ”€ confโ”‚ย ย  โ”œโ”€โ”€ config.yamlโ”‚ย ย  โ””โ”€โ”€ datasetโ”‚ย ย      โ””โ”€โ”€ cifar10.yamlโ”œโ”€โ”€ additonal_confโ”‚ย ย  โ”œโ”€โ”€ __init__.pyโ”‚ย ย  โ””โ”€โ”€ datasetโ”‚ย ย      โ””โ”€โ”€ imagenet.yamlโ””โ”€โ”€

@hydra.main(config_path="conf", config_name="config")def my_app(cfg: DictConfig) -> None:    print(OmegaConf.to_yaml(cfg))

if __name__ == "__main__":    my_app()

conf/config.yaml is the primary config for, config groups cifar10 and imagenet are under different folders. We can add additonal_conf to hydra.searchpath for Hydra to discover dataset/imagenet.

defaults:  - dataset: cifar10
hydra:  searchpath:    - pkg://additonal_conf    # You can also use file based schema:    # - file:///etc/my_app    # - file://${oc.env:HOME}/.my_app output
dataset:  name: cifar10  path: /datasets/cifar10

Overriding dataset=imagenet from the commandline:

command line override
python dataset=imagenet output
dataset:  name: imagenet  path: /datasets/imagenet

hydra.searchpath can be defined or overridden via the command line as well:

command line override
python 'hydra.searchpath=[pkg://additonal_conf]'

Overriding --config-dir from the command line#

This is a less flexible alternative to hydra.searchpath. See this page for more info.

Creating a SearchPathPlugin#

ย Example

Framework authors may want to add their configs to the search path automatically once their package is installed, eliminating the need for any actions from the users. This can be achieved using a SearchPathPlugin. Check the example plugin linked above for more details.