0
# python-dotenv
1

2
A Python library that reads key-value pairs from a `.env` file and can set them as environment variables. It helps in the development of applications following the 12-factor principles by providing a convenient way to manage configuration through environment variables.
3

4
## Package Information
5

6
- **Package Name**: python-dotenv
7
- **Language**: Python
8
- **Installation**: `pip install python-dotenv`
9
- **CLI Installation**: `pip install "python-dotenv[cli]"`
10

11
## Core Imports
12

13
```python
14
from dotenv import load_dotenv, dotenv_values
15
```
16

17
Complete imports for all functionality:
18

19
```python
20
from dotenv import (
21
    load_dotenv,
22
    dotenv_values,
23
    find_dotenv,
24
    get_key,
25
    set_key,
26
    unset_key,
27
    get_cli_string,
28
    load_ipython_extension
29
)
30
```
31

32
## Basic Usage
33

34
```python
35
from dotenv import load_dotenv
36
import os
37

38
# Load environment variables from .env file
39
load_dotenv()
40

41
# Now you can access environment variables
42
database_url = os.getenv('DATABASE_URL')
43
debug_mode = os.getenv('DEBUG', 'False').lower() == 'true'
44

45
# Use environment variables in your application
46
print(f"Database URL: {database_url}")
47
print(f"Debug mode: {debug_mode}")
48
```
49

50
Alternative approach without modifying environment:
51

52
```python
53
from dotenv import dotenv_values
54

55
# Parse .env file and return as dictionary
56
config = dotenv_values(".env")
57
database_url = config.get('DATABASE_URL')
58
debug_mode = config.get('DEBUG', 'False').lower() == 'true'
59
```
60

61
## Architecture
62

63
python-dotenv follows a modular architecture:
64

65
- **Loading Functions**: `load_dotenv()` and `dotenv_values()` provide the primary interfaces for loading configuration
66
- **File Discovery**: `find_dotenv()` automatically discovers .env files in the directory hierarchy
67
- **File Manipulation**: `get_key()`, `set_key()`, `unset_key()` provide programmatic access to .env file contents
68
- **Variable Expansion**: Built-in support for POSIX-style variable expansion using `${VAR}` syntax
69
- **CLI Interface**: Complete command-line tool for .env file manipulation
70
- **IPython Integration**: Magic commands for interactive development environments
71

72
## Capabilities
73

74
### Environment Loading
75

76
Load environment variables from .env files with automatic file discovery, variable expansion, and flexible override options.
77

78
```python { .api }
79
def load_dotenv(
80
    dotenv_path: Optional[Union[str, os.PathLike[str]]] = None,
81
    stream: Optional[IO[str]] = None,
82
    verbose: bool = False,
83
    override: bool = False,
84
    interpolate: bool = True,
85
    encoding: Optional[str] = "utf-8"
86
) -> bool: ...
87

88
def dotenv_values(
89
    dotenv_path: Optional[Union[str, os.PathLike[str]]] = None,
90
    stream: Optional[IO[str]] = None,
91
    verbose: bool = False,
92
    interpolate: bool = True,
93
    encoding: Optional[str] = "utf-8"
94
) -> Dict[str, Optional[str]]: ...
95

96
def find_dotenv(
97
    filename: str = ".env",
98
    raise_error_if_not_found: bool = False,
99
    usecwd: bool = False
100
) -> str: ...
101
```
102

103
[Environment Loading](./environment-loading.md)
104

105
### File Manipulation
106

107
Programmatically read, write, and modify .env files with support for different quote modes and export formats.
108

109
```python { .api }
110
def get_key(
111
    dotenv_path: Union[str, os.PathLike[str]],
112
    key_to_get: str,
113
    encoding: Optional[str] = "utf-8"
114
) -> Optional[str]: ...
115

116
def set_key(
117
    dotenv_path: Union[str, os.PathLike[str]],
118
    key_to_set: str,
119
    value_to_set: str,
120
    quote_mode: str = "always",
121
    export: bool = False,
122
    encoding: Optional[str] = "utf-8"
123
) -> Tuple[Optional[bool], str, str]: ...
124

125
def unset_key(
126
    dotenv_path: Union[str, os.PathLike[str]],
127
    key_to_unset: str,
128
    quote_mode: str = "always",
129
    encoding: Optional[str] = "utf-8"
130
) -> Tuple[Optional[bool], str]: ...
131
```
132

133
[File Manipulation](./file-manipulation.md)
134

135
### Command Line Interface
136

137
Complete CLI tool for managing .env files with list, get, set, unset, and run commands supporting multiple output formats.
138

139
```bash { .api }
140
dotenv list [--format=FORMAT]
141
dotenv get KEY
142
dotenv set KEY VALUE
143
dotenv unset KEY
144
dotenv run [--override/--no-override] COMMAND
145
```
146

147
[Command Line Interface](./cli.md)
148

149
### IPython Integration
150

151
Magic commands for loading .env files in IPython and Jupyter notebook environments with override and verbose options.
152

153
```python { .api }
154
def load_ipython_extension(ipython: Any) -> None: ...
155

156
# Magic command usage:
157
# %load_ext dotenv
158
# %dotenv [-o] [-v] [dotenv_path]
159
```
160

161
[IPython Integration](./ipython.md)
162

163
### Utility Functions
164

165
Helper functions for generating CLI commands and working with dotenv programmatically.
166

167
```python { .api }
168
def get_cli_string(
169
    path: Optional[str] = None,
170
    action: Optional[str] = None,
171
    key: Optional[str] = None,
172
    value: Optional[str] = None,
173
    quote: Optional[str] = None
174
) -> str: ...
175
```
176

177
[Utilities](./utilities.md)
178

179
## Types
180

181
```python { .api }
182
# Type aliases
183
StrPath = Union[str, os.PathLike[str]]
184

185
# Core classes (internal, accessed via functions)
186
class DotEnv:
187
    def __init__(
188
        self,
189
        dotenv_path: Optional[StrPath],
190
        stream: Optional[IO[str]] = None,
191
        verbose: bool = False,
192
        encoding: Optional[str] = None,
193
        interpolate: bool = True,
194
        override: bool = True
195
    ) -> None: ...
196
    
197
    def dict(self) -> Dict[str, Optional[str]]: ...
198
    def parse(self) -> Iterator[Tuple[str, Optional[str]]]: ...
199
    def set_as_environment_variables(self) -> bool: ...
200
    def get(self, key: str) -> Optional[str]: ...
201

202
# Parser types (internal implementation)
203
class Binding(NamedTuple):
204
    key: Optional[str]
205
    value: Optional[str]
206
    original: "Original"
207
    error: bool
208

209
class Original(NamedTuple):
210
    string: str
211
    line: int
212
```