0
# Hydra
1

2
A framework for elegantly configuring complex applications. Hydra simplifies the development of complex applications by providing elegant configuration management capabilities, enabling developers to compose and override configurations dynamically from the command line, and supporting hierarchical configuration with automatic merging.
3

4
## Package Information
5

6
- **Package Name**: hydra-core
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install hydra-core`
10
- **Pytest Integration**: Automatic via `hydra_pytest` entry point
11

12
## Core Imports
13

14
```python
15
import hydra
16
from hydra import main, compose, initialize, utils
17
from hydra.core.config_store import ConfigStore
18
```
19

20
Main decorator import:
21
```python
22
from hydra import main
23
```
24

25
Configuration composition:
26
```python
27
from hydra import compose, initialize
28
```
29

30
Utility functions:
31
```python
32
from hydra.utils import instantiate, get_class, get_method, get_original_cwd, to_absolute_path
33
```
34

35
## Basic Usage
36

37
```python
38
import hydra
39
from omegaconf import DictConfig
40

41
@hydra.main(version_base=None, config_path="conf", config_name="config")
42
def my_app(cfg: DictConfig) -> None:
43
    print(cfg.db.driver)
44
    print(cfg.db.user)
45
    print(cfg.db.password)
46

47
if __name__ == "__main__":
48
    my_app()
49
```
50

51
With structured configs:
52
```python
53
from dataclasses import dataclass
54
from hydra import main, initialize, compose
55
from hydra.core.config_store import ConfigStore
56
from omegaconf import DictConfig
57

58
@dataclass
59
class DatabaseConfig:
60
    driver: str
61
    user: str
62
    password: str
63

64
cs = ConfigStore.instance()
65
cs.store(name="config", node=DatabaseConfig)
66

67
@main(version_base=None, config_path=None, config_name="config")
68
def my_app(cfg: DatabaseConfig) -> None:
69
    print(f"Driver: {cfg.driver}")
70
    print(f"User: {cfg.user}")
71
    print(f"Password: {cfg.password}")
72

73
if __name__ == "__main__":
74
    my_app()
75
```
76

77
## Architecture
78

79
Hydra's architecture is built around several key components:
80

81
- **Configuration Management**: Hierarchical configuration composition with YAML files and structured configs
82
- **Decorator System**: The `@hydra.main` decorator wraps application functions and handles configuration injection
83
- **ConfigStore**: Singleton registry for structured configuration schemas
84
- **Global State**: GlobalHydra manages initialization state and configuration access
85
- **Plugin System**: Extensible launcher, sweeper, and config source plugins
86
- **Instantiation**: Automatic object creation from configuration with dependency injection
87

88
This design enables flexible configuration management patterns that scale from simple scripts to large distributed applications while maintaining clean separation between configuration and application logic.
89

90
## Capabilities
91

92
### Main Decorator and Application Entry Point
93

94
The core decorator that transforms regular Python functions into Hydra-enabled applications with automatic configuration management and command-line interface generation.
95

96
```python { .api }
97
def main(
98
    config_path: Optional[str] = None,
99
    config_name: Optional[str] = None,
100
    version_base: Optional[str] = None
101
) -> Callable[[TaskFunction], Any]: ...
102
```
103

104
[Main Decorator](./main-decorator.md)
105

106
### Configuration Composition
107

108
Dynamic configuration composition capabilities allowing runtime assembly of configurations from multiple sources with override support.
109

110
```python { .api }
111
def compose(
112
    config_name: Optional[str] = None,
113
    overrides: Optional[List[str]] = None,
114
    return_hydra_config: bool = False,
115
    strict: Optional[bool] = None
116
) -> DictConfig: ...
117
```
118

119
[Configuration Composition](./composition.md)
120

121
### Initialization Context Managers
122

123
Context managers for programmatic Hydra initialization in different scenarios including file-based configs, module-based configs, and absolute directory paths.
124

125
```python { .api }
126
class initialize:
127
    def __init__(
128
        self,
129
        config_path: Optional[str] = None,
130
        job_name: Optional[str] = None,
131
        caller_stack_depth: int = 1,
132
        version_base: Optional[str] = None
133
    ) -> None: ...
134

135
class initialize_config_module:
136
    def __init__(
137
        self,
138
        config_module: str,
139
        job_name: str = "app",
140
        version_base: Optional[str] = None
141
    ) -> None: ...
142

143
class initialize_config_dir:
144
    def __init__(
145
        self,
146
        config_dir: str,
147
        job_name: str = "app", 
148
        version_base: Optional[str] = None
149
    ) -> None: ...
150
```
151

152
[Initialization](./initialization.md)
153

154
### Object Instantiation and Utilities
155

156
Utility functions for dynamic object instantiation from configuration, path resolution, and reflection-based object access.
157

158
```python { .api }
159
def instantiate(config: Any, *args: Any, **kwargs: Any) -> Any: ...
160
def get_class(path: str) -> type: ...
161
def get_method(path: str) -> Callable[..., Any]: ...
162
def get_object(path: str) -> Any: ...
163
def get_original_cwd() -> str: ...
164
def to_absolute_path(path: str) -> str: ...
165
```
166

167
[Utilities](./utilities.md)
168

169
### Configuration Store and Structured Configs
170

171
Centralized registry for storing and managing structured configuration schemas with support for hierarchical organization and provider tracking.
172

173
```python { .api }
174
class ConfigStore:
175
    @staticmethod
176
    def instance() -> "ConfigStore": ...
177
    
178
    def store(
179
        self,
180
        name: str,
181
        node: Any,
182
        group: Optional[str] = None,
183
        package: Optional[str] = None,
184
        provider: Optional[str] = None
185
    ) -> None: ...
186
    
187
    def load(self, config_path: str) -> ConfigNode: ...
188
    def list(self, path: str) -> List[str]: ...
189
```
190

191
[Configuration Store](./config-store.md)
192

193
### Type System and Enums
194

195
Type definitions, dataclasses, and enums that provide structure for Hydra's configuration system and define behavior for different modes and conversion strategies.
196

197
```python { .api }
198
TaskFunction = Callable[[Any], Any]
199

200
class RunMode(Enum):
201
    RUN = 1
202
    MULTIRUN = 2
203

204
class ConvertMode(Enum):
205
    NONE = "none"
206
    PARTIAL = "partial"  
207
    OBJECT = "object"
208
    ALL = "all"
209
```
210

211
[Types and Enums](./types.md)
212

213
### Error Handling and Exceptions
214

215
Comprehensive exception hierarchy for handling configuration errors, instantiation failures, and other Hydra-specific error conditions.
216

217
```python { .api }
218
class HydraException(Exception): ...
219
class MissingConfigException(IOError, ConfigCompositionException): ...
220
class InstantiationException(CompactHydraException): ...
221
class ConfigCompositionException(CompactHydraException): ...
222
```
223

224
[Error Handling](./errors.md)
225

226
### Callback System
227

228
Experimental callback API for hooking into Hydra's execution lifecycle with support for run start/end, multirun events, and individual job events.
229

230
```python { .api }
231
class Callback:
232
    def on_run_start(self, config: DictConfig, **kwargs: Any) -> None: ...
233
    def on_run_end(self, config: DictConfig, **kwargs: Any) -> None: ...
234
    def on_multirun_start(self, config: DictConfig, **kwargs: Any) -> None: ...
235
    def on_multirun_end(self, config: DictConfig, **kwargs: Any) -> None: ...
236
    def on_job_start(self, config: DictConfig, *, task_function: TaskFunction, **kwargs: Any) -> None: ...
237
    def on_job_end(self, config: DictConfig, job_return: JobReturn, **kwargs: Any) -> None: ...
238
```
239

240
[Callbacks](./callbacks.md)
241

242
### Configuration Schema Classes
243

244
Structured configuration classes that define the schema for Hydra's internal configuration including job settings, runtime information, and hydra-specific options.
245

246
```python { .api }
247
@dataclass
248
class HydraConf:
249
    defaults: List[Any]
250
    mode: Optional[RunMode]
251
    searchpath: List[str]
252
    run: RunDir
253
    sweep: SweepDir
254
    # ... additional fields
255

256
@dataclass  
257
class JobConf:
258
    name: str
259
    chdir: Optional[bool]
260
    override_dirname: str
261
    # ... additional fields
262
```
263

264
[Configuration Schema](./config-schema.md)
265

266
## Types
267

268
```python { .api }
269
# Version and constants
270
__version__ = "1.3.2"
271

272
# Type aliases
273
TaskFunction = Callable[[Any], Any]
274

275
# Exception classes (key exports)
276
class MissingConfigException(IOError, ConfigCompositionException):
277
    """Raised when a required configuration cannot be found."""
278

279
# Core dataclasses
280
@dataclass
281
class HydraContext:
282
    config_loader: "ConfigLoader"
283
    callbacks: "Callbacks"
284

285
@dataclass
286
class ConfigNode:
287
    name: str
288
    node: DictConfig
289
    group: Optional[str]
290
    package: Optional[str]
291
    provider: Optional[str]
292

293
# Enums
294
class RunMode(Enum):
295
    RUN = 1
296
    MULTIRUN = 2
297

298
class ConvertMode(Enum):
299
    NONE = "none"
300
    PARTIAL = "partial"
301
    OBJECT = "object"
302
    ALL = "all"
303

304
class ObjectType(Enum):
305
    CONFIG = 1
306
    GROUP = 2
307
    NOT_FOUND = 3
308
```