0
# Main Decorator
1

2
The `@hydra.main` decorator is the primary entry point for Hydra-enabled applications. It transforms regular Python functions into configuration-aware applications with automatic command-line interface generation and configuration injection.
3

4
## Capabilities
5

6
### Main Decorator Function
7

8
Decorator that enables Hydra configuration management for application functions. When applied to a function, it automatically handles configuration loading, command-line argument parsing, and dependency injection.
9

10
```python { .api }
11
def main(
12
    config_path: Optional[str] = None,
13
    config_name: Optional[str] = None,
14
    version_base: Optional[str] = None
15
) -> Callable[[TaskFunction], Any]:
16
    """
17
    Decorator for Hydra-enabled applications.
18
    
19
    Parameters:
20
    - config_path: Directory where Hydra searches for config files. 
21
                   Relative paths are interpreted relative to the declaring python file.
22
                   Can use "pkg://" prefix to specify a python package.
23
                   If None, no directory is added to the config search path.
24
    - config_name: Name of the config file (usually without .yaml extension)
25
    - version_base: Hydra version compatibility base for behavior control
26
    
27
    Returns:
28
    Decorator function that wraps TaskFunction
29
    """
30
```
31

32
### Usage Examples
33

34
Basic usage with file-based configuration:
35

36
```python
37
@hydra.main(version_base=None, config_path="conf", config_name="config")
38
def my_app(cfg: DictConfig) -> None:
39
    print(cfg.db.driver)
40
    print(cfg.db.user)
41
```
42

43
Usage without configuration files:
44

45
```python
46
@hydra.main(version_base=None, config_path=None)
47
def my_app(cfg: DictConfig) -> None:
48
    # cfg will be empty DictConfig
49
    print("Running with no config")
50
```
51

52
Usage with package-based config path:
53

54
```python
55
@hydra.main(version_base=None, config_path="pkg://my_package.conf", config_name="config")
56
def my_app(cfg: DictConfig) -> None:
57
    print(cfg)
58
```
59

60
Command-line override examples:
61

62
```bash
63
# Override configuration values
64
python my_app.py db.driver=postgresql db.port=5432
65

66
# Run in multirun mode
67
python my_app.py --multirun db.driver=mysql,postgresql
68

69
# Change config file
70
python my_app.py --config-name=production
71
```
72

73
### Configuration Path Behavior
74

75
The `config_path` parameter supports several patterns:
76

77
- **Relative paths**: Interpreted relative to the Python file containing the decorator
78
- **Absolute paths**: Used as-is (not recommended)
79
- **Package paths**: Use `pkg://package.name` to reference Python package resources
80
- **None**: No config search path is added, useful for structured config-only applications
81

82
### Version Base Compatibility
83

84
The `version_base` parameter controls backward compatibility behavior:
85

86
- **None**: Use current version defaults (recommended for new applications)
87
- **"1.1"**: Use Hydra 1.1 compatible defaults
88
- **"1.2"**: Use Hydra 1.2 compatible defaults
89

90
### Task Function Requirements
91

92
The decorated function must accept a single parameter that is compatible with DictConfig:
93

94
```python
95
# Correct signatures
96
def my_app(cfg: DictConfig) -> None: ...
97
def my_app(cfg: Any) -> None: ...
98
def my_app(cfg) -> None: ...
99

100
# Incorrect - multiple parameters not supported
101
def my_app(cfg: DictConfig, other_param: str) -> None: ...  # Wrong!
102
```
103

104
### Return Values
105

106
The decorated function can return any value. In multirun mode, return values from all jobs are collected and can be accessed through job return objects in callbacks or launchers.
107

108
### Integration with Structured Configs
109

110
The main decorator works seamlessly with structured configurations stored in ConfigStore:
111

112
```python
113
from dataclasses import dataclass
114
from hydra.core.config_store import ConfigStore
115

116
@dataclass
117
class Config:
118
    name: str
119
    value: int
120

121
cs = ConfigStore.instance()
122
cs.store(name="config", node=Config)
123

124
@hydra.main(version_base=None, config_path=None, config_name="config")
125
def my_app(cfg: Config) -> None:  # Type hint matches stored config
126
    print(f"Name: {cfg.name}, Value: {cfg.value}")
127
```