0
# Configuration
1
2
Environment variable-based configuration system controlling pipenv behavior. The Setting class provides access to all configuration options and settings that control how pipenv operates.
3
4
## Capabilities
5
6
### Configuration Access
7
8
Access pipenv configuration through environment variables.
9
10
```python { .api }
11
class Setting:
12
"""
13
Configuration management through environment variables.
14
All settings are accessed as properties that read from environment variables.
15
50+ configuration options available.
16
"""
17
18
# Core directories and paths
19
PIPENV_CACHE_DIR: str # Cache directory location
20
PIPENV_VENV_IN_PROJECT: bool # Create venv in project directory
21
PIPENV_PIPFILE: str # Custom Pipfile location
22
PIPENV_DOTENV_LOCATION: str # Custom .env file location
23
24
# Python and environment management
25
PIPENV_PYTHON: str # Python executable path
26
PIPENV_DEFAULT_PYTHON_VERSION: str # Default Python version
27
PIPENV_DONT_USE_PYENV: bool # Disable pyenv integration
28
PIPENV_DONT_USE_ASDF: bool # Disable asdf integration
29
PIPENV_IGNORE_VIRTUALENVS: bool # Ignore existing virtualenvs
30
31
# Output and display control
32
PIPENV_VERBOSE: bool # Verbose output
33
PIPENV_QUIET: bool # Quiet output
34
PIPENV_NOSPIN: bool # Disable spinner animations
35
PIPENV_SPINNER: str # Spinner type
36
PIPENV_HIDE_EMOJIS: bool # Hide emoji output
37
38
# Package installation and resolution
39
PIPENV_PYPI_MIRROR: str # PyPI mirror URL
40
PIPENV_INSTALL_TIMEOUT: int # Package install timeout (900s)
41
PIPENV_TIMEOUT: int # Virtualenv creation timeout (120s)
42
PIPENV_REQUESTS_TIMEOUT: int # HTTP requests timeout (10s)
43
PIPENV_MAX_RETRIES: int # Network retry attempts
44
PIPENV_RESOLVE_VCS: bool # Resolve VCS dependencies
45
PIPENV_SKIP_LOCK: bool # Skip automatic locking
46
PIPENV_SKIP_VALIDATION: bool # Skip requirement validation
47
48
# Project discovery and behavior
49
PIPENV_MAX_DEPTH: int # Max directory search depth (10)
50
PIPENV_NO_INHERIT: bool # Don't inherit parent directories
51
52
# Shell and environment loading
53
PIPENV_SHELL_EXPLICIT: str # Preferred shell path
54
PIPENV_SHELL_FANCY: bool # Use fancy shell mode
55
PIPENV_EMULATOR: str # Terminal emulator name
56
PIPENV_DONT_LOAD_ENV: bool # Skip loading .env files
57
58
# Development and testing
59
PIPENV_TEST_INDEX: str # Test PyPI index URL
60
PIPENV_SITE_PACKAGES: bool # Include system site-packages
61
PIPENV_SYSTEM: bool # Use system pip
62
63
# Safety and security
64
PIPENV_PYUP_API_KEY: str # PyUp API key for safety checks
65
66
# Internal behavior
67
PIPENV_VIRTUALENV: str # Virtualenv location override
68
PIPENV_CUSTOM_VENV_NAME: str # Custom virtualenv name
69
USING_DEFAULT_PYTHON: bool # Whether using default Python
70
```
71
72
Usage examples:
73
```python
74
from pipenv.environments import Setting
75
76
settings = Setting()
77
78
# Check configuration
79
print(f"Cache directory: {settings.PIPENV_CACHE_DIR}")
80
print(f"Verbose mode: {settings.PIPENV_VERBOSE}")
81
print(f"Venv in project: {settings.PIPENV_VENV_IN_PROJECT}")
82
83
# Check behavior settings
84
if settings.PIPENV_SKIP_LOCK:
85
print("Automatic locking is disabled")
86
87
if settings.PIPENV_IGNORE_VIRTUALENVS:
88
print("Existing virtualenvs will be ignored")
89
```
90
91
### Directory Configuration
92
93
Control where pipenv stores files and creates environments.
94
95
```python { .api }
96
class Setting:
97
PIPENV_CACHE_DIR: str # Cache directory (default: ~/.cache/pipenv)
98
PIPENV_VENV_IN_PROJECT: bool # Create .venv in project directory
99
PIPENV_CUSTOM_VENV_NAME: str # Custom virtualenv name
100
PIPENV_DONT_USE_PYENV: bool # Don't use pyenv for Python resolution
101
```
102
103
Usage examples:
104
```python
105
import os
106
from pipenv.environments import Setting
107
108
settings = Setting()
109
110
# Configure cache directory
111
print(f"Cache directory: {settings.PIPENV_CACHE_DIR}")
112
113
# Check if venv should be in project
114
if settings.PIPENV_VENV_IN_PROJECT:
115
print("Virtual environment will be created in project/.venv")
116
else:
117
print("Virtual environment will be created in default location")
118
119
# Set custom cache directory
120
os.environ["PIPENV_CACHE_DIR"] = "/custom/cache/path"
121
```
122
123
### Output and Display Configuration
124
125
Control pipenv's output behavior and display formatting.
126
127
```python { .api }
128
class Setting:
129
PIPENV_VERBOSE: bool # Enable verbose output
130
PIPENV_QUIET: bool # Enable quiet mode
131
PIPENV_COLORBLIND: bool # Disable colored output
132
PIPENV_NOSPIN: bool # Disable spinner animations
133
PIPENV_HIDE_EMOJIS: bool # Hide emoji characters
134
PIPENV_NO_INHERIT: bool # Don't inherit parent shell settings
135
```
136
137
Usage examples:
138
```python
139
import os
140
from pipenv.environments import Setting
141
142
# Enable verbose mode
143
os.environ["PIPENV_VERBOSE"] = "1"
144
settings = Setting()
145
146
if settings.PIPENV_VERBOSE:
147
print("Verbose mode enabled - detailed output will be shown")
148
149
# Configure for CI/automation
150
os.environ["PIPENV_QUIET"] = "1"
151
os.environ["PIPENV_NOSPIN"] = "1"
152
os.environ["PIPENV_HIDE_EMOJIS"] = "1"
153
154
settings = Setting()
155
print(f"Quiet mode: {settings.PIPENV_QUIET}")
156
print(f"Spinner disabled: {settings.PIPENV_NOSPIN}")
157
```
158
159
### Python and Environment Configuration
160
161
Control Python interpreter selection and environment behavior.
162
163
```python { .api }
164
class Setting:
165
PIPENV_PYTHON: str # Specific Python executable
166
PIPENV_DEFAULT_PYTHON_VERSION: str # Default Python version
167
PIPENV_DONT_USE_PYENV: bool # Disable pyenv integration
168
PIPENV_IGNORE_VIRTUALENVS: bool # Ignore existing virtualenvs
169
PIPENV_SHELL_FANCY: bool # Use fancy shell prompt
170
PIPENV_SHELL: str # Shell executable to use
171
```
172
173
Usage examples:
174
```python
175
import os
176
from pipenv.environments import Setting
177
178
# Configure Python version
179
os.environ["PIPENV_PYTHON"] = "3.9"
180
os.environ["PIPENV_DEFAULT_PYTHON_VERSION"] = "3.9"
181
182
settings = Setting()
183
print(f"Python executable: {settings.PIPENV_PYTHON}")
184
print(f"Default version: {settings.PIPENV_DEFAULT_PYTHON_VERSION}")
185
186
# Disable pyenv
187
os.environ["PIPENV_DONT_USE_PYENV"] = "1"
188
if settings.PIPENV_DONT_USE_PYENV:
189
print("pyenv integration disabled")
190
191
# Configure shell
192
os.environ["PIPENV_SHELL_FANCY"] = "1"
193
os.environ["PIPENV_SHELL"] = "/bin/zsh"
194
```
195
196
### Network and Package Configuration
197
198
Control package installation and network behavior.
199
200
```python { .api }
201
class Setting:
202
PIPENV_PYPI_MIRROR: str # PyPI mirror URL
203
PIPENV_TIMEOUT: int # Network timeout seconds
204
PIPENV_INSTALL_TIMEOUT: int # Package install timeout
205
PIPENV_RESOLVE_VCS: bool # Resolve VCS dependencies
206
PIPENV_SKIP_VALIDATION: bool # Skip requirement validation
207
PIPENV_MAX_RETRIES: int # Max retry attempts
208
```
209
210
Usage examples:
211
```python
212
import os
213
from pipenv.environments import Setting
214
215
# Configure PyPI mirror
216
os.environ["PIPENV_PYPI_MIRROR"] = "https://pypi.example.com/simple"
217
os.environ["PIPENV_TIMEOUT"] = "120"
218
os.environ["PIPENV_INSTALL_TIMEOUT"] = "900"
219
220
settings = Setting()
221
print(f"PyPI mirror: {settings.PIPENV_PYPI_MIRROR}")
222
print(f"Network timeout: {settings.PIPENV_TIMEOUT}")
223
print(f"Install timeout: {settings.PIPENV_INSTALL_TIMEOUT}")
224
225
# Configure VCS resolution
226
os.environ["PIPENV_RESOLVE_VCS"] = "1"
227
if settings.PIPENV_RESOLVE_VCS:
228
print("VCS dependencies will be resolved")
229
```
230
231
### Locking and Dependency Configuration
232
233
Control dependency resolution and lock file behavior.
234
235
```python { .api }
236
class Setting:
237
PIPENV_SKIP_LOCK: bool # Skip automatic lock generation
238
PIPENV_MAX_DEPTH: int # Max Pipfile search depth
239
PIPENV_PIPFILE: str # Custom Pipfile location
240
PIPENV_DONT_LOAD_ENV: bool # Don't load .env files
241
PIPENV_DOTENV_LOCATION: str # Custom .env file location
242
```
243
244
Usage examples:
245
```python
246
import os
247
from pipenv.environments import Setting
248
249
# Configure locking behavior
250
os.environ["PIPENV_SKIP_LOCK"] = "1"
251
os.environ["PIPENV_MAX_DEPTH"] = "5"
252
253
settings = Setting()
254
if settings.PIPENV_SKIP_LOCK:
255
print("Automatic lock file generation disabled")
256
print(f"Max search depth: {settings.PIPENV_MAX_DEPTH}")
257
258
# Configure custom Pipfile
259
os.environ["PIPENV_PIPFILE"] = "/custom/path/Pipfile"
260
print(f"Custom Pipfile: {settings.PIPENV_PIPFILE}")
261
262
# Configure .env file handling
263
os.environ["PIPENV_DONT_LOAD_ENV"] = "1"
264
os.environ["PIPENV_DOTENV_LOCATION"] = "/custom/.env"
265
```
266
267
### Security and Validation Configuration
268
269
Control security checks and validation behavior.
270
271
```python { .api }
272
class Setting:
273
PIPENV_CHECK_FLAGS: str # Safety check flags
274
PIPENV_IGNORE_PIPFILE: bool # Ignore Pipfile for installs
275
PIPENV_SKIP_VALIDATION: bool # Skip requirement validation
276
PIPENV_EMULATOR: str # Terminal emulator for shell
277
```
278
279
Usage examples:
280
```python
281
import os
282
from pipenv.environments import Setting
283
284
# Configure security checks
285
os.environ["PIPENV_CHECK_FLAGS"] = "--db /custom/safety-db"
286
settings = Setting()
287
print(f"Safety check flags: {settings.PIPENV_CHECK_FLAGS}")
288
289
# Configure validation
290
os.environ["PIPENV_SKIP_VALIDATION"] = "1"
291
if settings.PIPENV_SKIP_VALIDATION:
292
print("Requirement validation disabled")
293
```
294
295
## Configuration File Support
296
297
While pipenv primarily uses environment variables, it also supports configuration files.
298
299
### Environment Variables in .env Files
300
301
```python
302
# .env file content
303
PIPENV_VENV_IN_PROJECT=1
304
PIPENV_VERBOSE=1
305
PIPENV_PYTHON=3.9
306
PIPENV_PYPI_MIRROR=https://pypi.example.com/simple
307
```
308
309
Usage in code:
310
```python
311
from pipenv.environments import Setting
312
313
# pipenv automatically loads .env files
314
settings = Setting()
315
316
# Settings from .env are available
317
print(f"Venv in project: {settings.PIPENV_VENV_IN_PROJECT}")
318
print(f"Verbose mode: {settings.PIPENV_VERBOSE}")
319
```
320
321
### Dynamic Configuration
322
323
Change configuration at runtime:
324
325
```python
326
import os
327
from pipenv.environments import Setting
328
329
# Initial settings
330
settings = Setting()
331
print(f"Initial verbose: {settings.PIPENV_VERBOSE}")
332
333
# Change environment variable
334
os.environ["PIPENV_VERBOSE"] = "1"
335
336
# Create new Setting instance to pick up changes
337
new_settings = Setting()
338
print(f"Updated verbose: {new_settings.PIPENV_VERBOSE}")
339
```
340
341
## Common Configuration Patterns
342
343
### Development Environment
344
345
```python
346
import os
347
348
# Development-friendly settings
349
os.environ.update({
350
"PIPENV_VENV_IN_PROJECT": "1", # Keep venv in project
351
"PIPENV_VERBOSE": "1", # Detailed output
352
"PIPENV_SHELL_FANCY": "1", # Nice shell prompt
353
"PIPENV_IGNORE_VIRTUALENVS": "0", # Use existing venvs
354
})
355
```
356
357
### CI/CD Environment
358
359
```python
360
import os
361
362
# CI/CD-friendly settings
363
os.environ.update({
364
"PIPENV_QUIET": "1", # Minimal output
365
"PIPENV_NOSPIN": "1", # No animations
366
"PIPENV_HIDE_EMOJIS": "1", # No emojis
367
"PIPENV_COLORBLIND": "1", # No colors
368
"PIPENV_SKIP_LOCK": "0", # Always generate locks
369
"PIPENV_INSTALL_TIMEOUT": "1200", # Longer timeout
370
})
371
```
372
373
### Corporate Network Environment
374
375
```python
376
import os
377
378
# Corporate network settings
379
os.environ.update({
380
"PIPENV_PYPI_MIRROR": "https://corporate-pypi.company.com/simple",
381
"PIPENV_TIMEOUT": "60", # Shorter timeout
382
"PIPENV_MAX_RETRIES": "5", # More retries
383
"PIPENV_CACHE_DIR": "/shared/cache/pipenv", # Shared cache
384
})
385
```
386
387
## Configuration Validation
388
389
Validate configuration settings:
390
391
```python
392
from pipenv.environments import Setting
393
import os
394
from pathlib import Path
395
396
def validate_configuration():
397
"""Validate pipenv configuration settings."""
398
settings = Setting()
399
400
# Validate cache directory
401
cache_dir = Path(settings.PIPENV_CACHE_DIR)
402
if not cache_dir.exists():
403
print(f"Warning: Cache directory does not exist: {cache_dir}")
404
405
# Validate Python executable
406
if settings.PIPENV_PYTHON:
407
python_path = Path(settings.PIPENV_PYTHON)
408
if not python_path.exists():
409
print(f"Warning: Python executable not found: {python_path}")
410
411
# Check for conflicting settings
412
if settings.PIPENV_VERBOSE and settings.PIPENV_QUIET:
413
print("Warning: Both verbose and quiet modes enabled")
414
415
# Validate timeout values
416
if settings.PIPENV_TIMEOUT and settings.PIPENV_TIMEOUT < 30:
417
print("Warning: Network timeout may be too short")
418
419
validate_configuration()
420
```
421
422
## Configuration Debugging
423
424
Debug configuration issues:
425
426
```python
427
from pipenv.environments import Setting
428
import os
429
430
def debug_configuration():
431
"""Debug pipenv configuration."""
432
settings = Setting()
433
434
print("=== Pipenv Configuration ===")
435
436
# Core settings
437
config_vars = [
438
"PIPENV_CACHE_DIR", "PIPENV_VENV_IN_PROJECT", "PIPENV_VERBOSE",
439
"PIPENV_QUIET", "PIPENV_PYTHON", "PIPENV_PYPI_MIRROR",
440
"PIPENV_SKIP_LOCK", "PIPENV_MAX_DEPTH", "PIPENV_TIMEOUT"
441
]
442
443
for var in config_vars:
444
value = getattr(settings, var, None)
445
env_value = os.environ.get(var, "Not set")
446
print(f"{var}: {value} (env: {env_value})")
447
448
debug_configuration()
449
```