0
# IPython Integration
1

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

4
## Installation
5

6
The IPython extension is included with the base python-dotenv package:
7

8
```bash
9
pip install python-dotenv
10
```
11

12
## Capabilities
13

14
### Loading the Extension
15

16
Load the dotenv extension to enable the `%dotenv` magic command.
17

18
```python { .api }
19
def load_ipython_extension(ipython: Any) -> None:
20
    """
21
    Register the %dotenv magic command.
22
    
23
    This function is called automatically when the extension is loaded.
24
    """
25
```
26

27
Usage in IPython/Jupyter:
28

29
```python
30
# Load the extension
31
%load_ext dotenv
32

33
# Extension is now available for the current session
34
```
35

36
### Magic Command
37

38
Use the `%dotenv` magic command to load environment variables from .env files.
39

40
```python { .api }
41
%dotenv [OPTIONS] [dotenv_path]
42

43
Options:
44
  -o, --override    Indicate to override existing variables
45
  -v, --verbose     Indicate function calls to be verbose
46

47
Arguments:
48
  dotenv_path       Search in increasingly higher folders for the dotenv_path (default: '.env')
49
```
50

51
## Usage Examples
52

53
### Basic Usage
54

55
```python
56
# Load extension
57
%load_ext dotenv
58

59
# Load from default .env file
60
%dotenv
61

62
# Now environment variables from .env are available
63
import os
64
database_url = os.getenv('DATABASE_URL')
65
print(f"Database URL: {database_url}")
66
```
67

68
### Loading from Specific Files
69

70
```python
71
# Load from specific file in current directory
72
%dotenv config.env
73

74
# Load from relative path
75
%dotenv ../shared.env
76

77
# Load from absolute path
78
%dotenv /path/to/production.env
79
```
80

81
### Using Options
82

83
```python
84
# Load with verbose output
85
%dotenv -v
86
# Output: Loading .env file found at: /current/directory/.env
87

88
# Override existing environment variables
89
%dotenv -o
90

91
# Combine options
92
%dotenv -o -v production.env
93
```
94

95
### Multiple Environment Files
96

97
```python
98
# Load multiple files in sequence
99
%dotenv shared.env
100
%dotenv -o local.env    # Override with local settings
101

102
# Load different files for different purposes
103
%dotenv database.env    # Database configuration
104
%dotenv api.env         # API keys and endpoints
105
%dotenv -o debug.env    # Debug settings (override existing)
106
```
107

108
## Integration with Jupyter Notebooks
109

110
The IPython integration is particularly useful in Jupyter notebooks for data science and development workflows:
111

112
```python
113
# Cell 1: Load environment configuration
114
%load_ext dotenv
115
%dotenv -v config.env
116

117
# Cell 2: Use environment variables
118
import os
119
import pandas as pd
120
from sqlalchemy import create_engine
121

122
# Get database connection from environment
123
database_url = os.getenv('DATABASE_URL')
124
engine = create_engine(database_url)
125

126
# Load data
127
df = pd.read_sql('SELECT * FROM users', engine)
128
df.head()
129
```
130

131
```python
132
# Example: Different environments for different notebook sections
133
# Development section
134
%dotenv -v development.env
135

136
# Load development data
137
dev_api_key = os.getenv('API_KEY')
138
dev_data = fetch_data(dev_api_key)
139

140
# Production comparison section  
141
%dotenv -o production.env
142

143
# Load production data
144
prod_api_key = os.getenv('API_KEY')
145
prod_data = fetch_data(prod_api_key)
146

147
# Compare datasets
148
compare_data(dev_data, prod_data)
149
```
150

151
## Options Details
152

153
### Override Option (`-o, --override`)
154

155
Controls whether environment variables from the .env file override existing environment variables:
156

157
```python
158
# Without override (default behavior)
159
import os
160
os.environ['DEBUG'] = 'False'    # Set in current environment
161
%dotenv                          # .env contains DEBUG=True
162
print(os.getenv('DEBUG'))        # Prints: False (existing value preserved)
163

164
# With override
165
import os
166
os.environ['DEBUG'] = 'False'    # Set in current environment
167
%dotenv -o                       # .env contains DEBUG=True  
168
print(os.getenv('DEBUG'))        # Prints: True (overridden by .env)
169
```
170

171
### Verbose Option (`-v, --verbose`)
172

173
Enables verbose output to show which .env file is being loaded:
174

175
```python
176
# Without verbose
177
%dotenv config.env
178
# (no output)
179

180
# With verbose
181
%dotenv -v config.env
182
# Output: Loading .env file found at: /current/directory/config.env
183
```
184

185
## Error Handling
186

187
The magic command handles common error scenarios gracefully:
188

189
```python
190
# File not found
191
%dotenv nonexistent.env
192
# Output: cannot find .env file
193

194
# No file specified and no default .env
195
%dotenv
196
# (silently continues if no .env file found)
197

198
# With verbose, shows search behavior
199
%dotenv -v
200
# Output: Loading .env file found at: /path/to/.env
201
# Or: python-dotenv could not find configuration file .env
202
```
203

204
## Automatic Extension Loading
205

206
For convenience, you can automatically load the extension when starting IPython by adding it to your IPython configuration:
207

208
```python
209
# In ~/.ipython/profile_default/ipython_config.py
210
c.InteractiveShellApp.extensions = ['dotenv']
211

212
# Or add to startup file
213
# In ~/.ipython/profile_default/startup/00-dotenv.py
214
get_ipython().magic('load_ext dotenv')
215
```
216

217
## Working with Virtual Environments
218

219
The IPython integration works seamlessly with virtual environments:
220

221
```python
222
# In a virtual environment
223
%load_ext dotenv
224
%dotenv -v
225

226
# Variables are loaded for the current Python session
227
import os
228
print(f"Virtual env: {os.getenv('VIRTUAL_ENV')}")
229
print(f"App config: {os.getenv('APP_CONFIG')}")
230
```
231

232
## Best Practices
233

234
1. **Load early**: Load your .env files early in your notebook before importing other modules
235
2. **Use verbose mode**: Use `-v` for debugging to see which files are being loaded
236
3. **Organize by purpose**: Use separate .env files for different configurations (database, API keys, debug settings)
237
4. **Override carefully**: Use `-o` only when you need to override existing environment variables
238
5. **Document in notebooks**: Add markdown cells explaining which .env files are needed
239

240
```python
241
# Good practice example
242
%load_ext dotenv
243

244
# Load base configuration
245
%dotenv -v base.env
246

247
# Load environment-specific overrides
248
%dotenv -o -v development.env
249

250
# Now proceed with analysis
251
import pandas as pd
252
import requests
253

254
api_key = os.getenv('API_KEY')
255
database_url = os.getenv('DATABASE_URL')
256
```