0
# Configuration Composition
1

2
Dynamic configuration composition capabilities that allow runtime assembly of configurations from multiple sources with override support. This enables programmatic configuration creation outside of the main application decorator.
3

4
## Capabilities
5

6
### Compose Function
7

8
Composes configuration dynamically from registered sources, applying overrides and returning a fully merged configuration object.
9

10
```python { .api }
11
def compose(
12
    config_name: Optional[str] = None,
13
    overrides: Optional[List[str]] = None,
14
    return_hydra_config: bool = False,
15
    strict: Optional[bool] = None
16
) -> DictConfig:
17
    """
18
    Compose configuration dynamically.
19
    
20
    Parameters:
21
    - config_name: Name of the config to compose (usually without .yaml extension)
22
    - overrides: List of configuration overrides in the format ["key=value", "nested.key=value"]
23
    - return_hydra_config: If True, includes hydra configuration node in result
24
    - strict: DEPRECATED. Previously controlled struct mode behavior
25
    
26
    Returns:
27
    DictConfig: Composed configuration object
28
    
29
    Raises:
30
    AssertionError: If GlobalHydra is not initialized
31
    """
32
```
33

34
### Initialization Requirement
35

36
The `compose` function requires Hydra to be initialized first using one of the initialization context managers:
37

38
```python
39
from hydra import initialize, compose
40

41
# Must initialize before composing
42
with initialize(version_base=None, config_path="conf"):
43
    cfg = compose(config_name="config")
44
    print(cfg)
45
```
46

47
### Usage Examples
48

49
Basic composition:
50

51
```python
52
from hydra import initialize, compose
53

54
with initialize(version_base=None, config_path="conf"):
55
    # Compose default config
56
    cfg = compose(config_name="config")
57
    
58
    # Compose with overrides
59
    cfg_override = compose(
60
        config_name="config",
61
        overrides=["db.driver=postgresql", "db.port=5432"]
62
    )
63
    
64
    # Include hydra configuration
65
    cfg_with_hydra = compose(
66
        config_name="config",
67
        return_hydra_config=True
68
    )
69
```
70

71
Composition with structured configs:
72

73
```python
74
from dataclasses import dataclass
75
from hydra import initialize_config_module, compose
76
from hydra.core.config_store import ConfigStore
77

78
@dataclass
79
class DatabaseConfig:
80
    driver: str = "mysql"
81
    port: int = 3306
82

83
cs = ConfigStore.instance()
84
cs.store(name="config", node=DatabaseConfig)
85

86
with initialize_config_module(version_base=None, config_module="conf"):
87
    cfg = compose(config_name="config")
88
    
89
    # Override structured config values
90
    cfg_postgres = compose(
91
        config_name="config",
92
        overrides=["driver=postgresql", "port=5432"]
93
    )
94
```
95

96
### Override Syntax
97

98
The overrides parameter supports Hydra's full override syntax:
99

100
```python
101
overrides = [
102
    "db.driver=postgresql",           # Simple value assignment
103
    "db.port=5432",                   # Numeric values
104
    "db.ssl=true",                    # Boolean values  
105
    "db.hosts=[host1,host2,host3]",   # List values
106
    "+new_key=value",                 # Add new key
107
    "~optional_key",                  # Delete key
108
    "db=postgres",                    # Config group selection
109
]
110

111
cfg = compose(config_name="config", overrides=overrides)
112
```
113

114
### Config Group Selection
115

116
Use overrides to select different configurations from config groups:
117

118
```python
119
# With config groups: conf/db/mysql.yaml and conf/db/postgres.yaml
120
cfg_mysql = compose(
121
    config_name="config",
122
    overrides=["db=mysql"]
123
)
124

125
cfg_postgres = compose(
126
    config_name="config", 
127
    overrides=["db=postgres"]
128
)
129
```
130

131
### Return Hydra Config
132

133
When `return_hydra_config=True`, the result includes Hydra's internal configuration:
134

135
```python
136
cfg = compose(config_name="config", return_hydra_config=True)
137

138
# Access Hydra configuration
139
print(cfg.hydra.job.name)
140
print(cfg.hydra.runtime.cwd)
141
print(cfg.hydra.runtime.output_dir)
142

143
# Access application configuration  
144
print(cfg.db.driver)  # Application config is at root level
145
```
146

147
### Error Handling
148

149
Common errors and their causes:
150

151
```python
152
# AssertionError - GlobalHydra not initialized
153
try:
154
    cfg = compose(config_name="config")  # Will fail!
155
except AssertionError as e:
156
    print("Must initialize Hydra first")
157

158
# MissingConfigException - Config not found
159
with initialize(version_base=None, config_path="conf"):
160
    try:
161
        cfg = compose(config_name="nonexistent")
162
    except MissingConfigException as e:
163
        print(f"Config not found: {e}")
164
```
165

166
### Integration with Different Initialization Methods
167

168
The compose function works with all initialization context managers:
169

170
```python
171
# File-based initialization
172
with initialize(version_base=None, config_path="conf"):
173
    cfg = compose(config_name="config")
174

175
# Module-based initialization  
176
with initialize_config_module(version_base=None, config_module="my_app.conf"):
177
    cfg = compose(config_name="config")
178

179
# Directory-based initialization
180
with initialize_config_dir(version_base=None, config_dir="/absolute/path/conf"):
181
    cfg = compose(config_name="config")
182
```