0
# Configuration Management
1

2
Comprehensive configuration system for managing Poetry settings, package sources, and environment preferences. Handles both global and project-specific configuration options through a hierarchical configuration system.
3

4
## Capabilities
5

6
### Configuration System
7

8
Central configuration management providing access to Poetry settings, repository configurations, virtual environment preferences, and caching options.
9

10
```python { .api }
11
class Config:
12
    """
13
    Poetry configuration management system.
14
    
15
    Handles global configuration, user preferences, and project-specific
16
    settings with support for configuration merging and validation.
17
    """
18
    
19
    @property
20
    def default_config(self) -> dict:
21
        """Default configuration values."""
22
    
23
    @property
24
    def repository_cache_directory(self) -> Path:
25
        """Cache directory for repository data."""
26
    
27
    @property
28
    def artifacts_cache_directory(self) -> Path:
29
        """Cache directory for package artifacts."""
30
    
31
    @property
32
    def virtualenvs_path(self) -> Path:
33
        """Base path for virtual environments."""
34
    
35
    @property
36
    def python_installation_dir(self) -> Path:
37
        """Directory for Python installations."""
38
    
39
    @property
40
    def installer_max_workers(self) -> int:
41
        """Maximum parallel workers for installation."""
42
    
43
    def get(self, setting_name: str, default = None):
44
        """
45
        Get configuration value by name.
46
        
47
        Args:
48
            setting_name: Configuration key (supports dot notation)
49
            default: Default value if not found
50
            
51
        Returns:
52
            Configuration value or default
53
        """
54
    
55
    def merge(self, config: dict) -> Config:
56
        """
57
        Merge configuration with existing settings.
58
        
59
        Args:
60
            config: Configuration dictionary to merge
61
            
62
        Returns:
63
            Self for method chaining
64
        """
65
    
66
    def all(self) -> dict:
67
        """
68
        Get all configuration as dictionary.
69
        
70
        Returns:
71
            Complete configuration dictionary
72
        """
73
    
74
    @staticmethod
75
    def create(reload: bool = False) -> Config:
76
        """
77
        Create default configuration instance.
78
        
79
        Args:
80
            reload: Whether to reload configuration from files
81
            
82
        Returns:
83
            Configured Config instance
84
        """
85
```
86

87
#### Usage Example
88

89
```python
90
from poetry.config.config import Config
91

92
# Create configuration instance
93
config = Config.create()
94

95
# Get configuration values
96
cache_dir = config.get("cache-dir")
97
venv_path = config.get("virtualenvs.path")
98
parallel_workers = config.get("installer.max-workers", 4)
99

100
# Access properties
101
print(f"Artifacts cache: {config.artifacts_cache_directory}")
102
print(f"Virtual envs: {config.virtualenvs_path}")
103
print(f"Max workers: {config.installer_max_workers}")
104

105
# Merge custom configuration
106
config.merge({
107
    "virtualenvs.create": True,
108
    "virtualenvs.in-project": False,
109
    "repositories.custom": {
110
        "url": "https://my-repo.com/simple/"
111
    }
112
})
113

114
# Get all configuration
115
all_config = config.all()
116
```
117

118
### Package Sources
119

120
Configuration and management of package repositories and sources with support for priorities and authentication.
121

122
```python { .api }
123
class Source:
124
    """
125
    Package source configuration.
126
    
127
    Represents a package repository source with priority handling
128
    and conversion utilities for different configuration formats.
129
    """
130
    
131
    name: str      # Source name/identifier
132
    url: str       # Repository URL
133
    priority: str  # Source priority (default, primary, supplemental, explicit)
134
    
135
    def to_dict(self) -> dict:
136
        """
137
        Convert source to dictionary representation.
138
        
139
        Returns:
140
            Dictionary with source configuration
141
        """
142
    
143
    def to_toml_table(self) -> dict:
144
        """
145
        Convert source to TOML table format.
146
        
147
        Returns:
148
            Dictionary formatted for TOML serialization
149
        """
150
```
151

152
#### Usage Example
153

154
```python
155
from poetry.config.source import Source
156

157
# Create package source
158
source = Source(
159
    name="private-repo",
160
    url="https://my-private-repo.com/simple/",
161
    priority="primary"
162
)
163

164
# Convert to different formats
165
source_dict = source.to_dict()
166
toml_data = source.to_toml_table()
167

168
# Use in pyproject.toml configuration
169
pyproject_sources = [
170
    {
171
        "name": "pypi",
172
        "url": "https://pypi.org/simple/",
173
        "priority": "default"
174
    },
175
    source.to_dict()
176
]
177
```
178

179
### Configuration Keys
180

181
Standard configuration keys and their purposes:
182

183
```python { .api }
184
# Cache configuration
185
CACHE_DIR = "cache-dir"                    # Base cache directory
186
ARTIFACTS_CACHE_DIR = "cache.artifacts"    # Package artifacts cache
187
REPOSITORY_CACHE_DIR = "cache.repositories" # Repository metadata cache
188

189
# Virtual environment configuration  
190
VIRTUALENVS_CREATE = "virtualenvs.create"     # Auto-create virtual environments
191
VIRTUALENVS_IN_PROJECT = "virtualenvs.in-project"  # Create .venv in project
192
VIRTUALENVS_PATH = "virtualenvs.path"         # Base path for virtual environments
193
VIRTUALENVS_PREFER_ACTIVE_PYTHON = "virtualenvs.prefer-active-python"
194

195
# Installation configuration
196
INSTALLER_MAX_WORKERS = "installer.max-workers"  # Parallel installation workers
197
INSTALLER_NO_BINARY = "installer.no-binary"      # Disable binary packages
198
INSTALLER_MODERN_INSTALLATION = "installer.modern-installation"
199

200
# Repository configuration
201
REPOSITORIES = "repositories"                # Custom repositories
202
PYPI_TOKEN = "pypi-token"                   # PyPI authentication token
203
HTTP_BASIC_AUTH = "http-basic"              # HTTP basic authentication
204

205
# Solver configuration
206
SOLVER_LAZY_WHEEL = "solver.lazy-wheel"     # Lazy wheel building
207
```
208

209
#### Configuration Usage Example
210

211
```python
212
from poetry.config.config import Config
213

214
config = Config.create()
215

216
# Virtual environment settings
217
config.merge({
218
    "virtualenvs.create": True,
219
    "virtualenvs.in-project": False,
220
    "virtualenvs.path": "/custom/venv/path",
221
    "virtualenvs.prefer-active-python": True
222
})
223

224
# Installation settings
225
config.merge({
226
    "installer.max-workers": 8,
227
    "installer.modern-installation": True
228
})
229

230
# Repository authentication
231
config.merge({
232
    "http-basic.private-repo.username": "user",
233
    "http-basic.private-repo.password": "pass",
234
    "repositories.private-repo.url": "https://private-repo.com/simple/"
235
})
236

237
# Cache settings
238
config.merge({
239
    "cache-dir": "/custom/cache/dir",
240
    "solver.lazy-wheel": True
241
})
242
```
243

244
### Configuration File Locations
245

246
Poetry reads configuration from multiple locations in order of precedence:
247

248
```python { .api }
249
def get_config_locations() -> list[Path]:
250
    """
251
    Get configuration file locations in order of precedence.
252
    
253
    Returns:
254
        List of configuration file paths
255
    """
256

257
def get_user_config_dir() -> Path:
258
    """
259
    Get user-specific configuration directory.
260
    
261
    Returns:
262
        Path to user configuration directory
263
    """
264

265
def get_system_config_dir() -> Path:
266
    """
267
    Get system-wide configuration directory.
268
    
269
    Returns:
270
        Path to system configuration directory
271
    """
272
```
273

274
Configuration precedence (highest to lowest):
275
1. Environment variables (`POETRY_*`)
276
2. Command-line options
277
3. Project-local configuration (`.poetry/config.toml`)
278
4. User configuration (`~/.config/pypoetry/config.toml`)
279
5. System configuration
280
6. Default values
281

282
### Environment Variable Configuration
283

284
Poetry configuration can be overridden using environment variables:
285

286
```python
287
# Virtual environment settings
288
POETRY_VIRTUALENVS_CREATE=false
289
POETRY_VIRTUALENVS_IN_PROJECT=true
290
POETRY_VIRTUALENVS_PATH=/custom/path
291

292
# Cache settings
293
POETRY_CACHE_DIR=/custom/cache
294
POETRY_NO_INTERACTION=1
295

296
# Repository settings
297
POETRY_REPOSITORIES_CUSTOM_URL=https://repo.example.com/simple/
298
POETRY_HTTP_BASIC_CUSTOM_USERNAME=user
299
POETRY_HTTP_BASIC_CUSTOM_PASSWORD=pass
300

301
# Installation settings
302
POETRY_INSTALLER_MAX_WORKERS=4
303
POETRY_INSTALLER_MODERN_INSTALLATION=true
304
```
305

306
### Advanced Configuration Patterns
307

308
#### Custom Repository Configuration
309

310
```python
311
from poetry.config.config import Config
312
from poetry.config.source import Source
313

314
config = Config.create()
315

316
# Add custom repository with authentication
317
config.merge({
318
    "repositories.company-internal": {
319
        "url": "https://internal-repo.company.com/simple/"
320
    },
321
    "http-basic.company-internal.username": "employee",
322
    "http-basic.company-internal.password": "secure-token"
323
})
324

325
# Create source for pyproject.toml
326
internal_source = Source(
327
    name="company-internal",
328
    url="https://internal-repo.company.com/simple/",
329
    priority="supplemental"
330
)
331
```
332

333
#### Development Environment Setup
334

335
```python
336
from poetry.config.config import Config
337

338
def setup_dev_config():
339
    """Configure Poetry for development environment."""
340
    config = Config.create()
341
    
342
    # Development-friendly settings
343
    config.merge({
344
        "virtualenvs.in-project": True,      # .venv in project
345
        "virtualenvs.prefer-active-python": True,  # Use active Python
346
        "installer.max-workers": 1,          # Sequential for debugging
347
        "solver.lazy-wheel": False,          # Build wheels eagerly
348
        "cache-dir": "./dev-cache"           # Local cache
349
    })
350
    
351
    return config
352
```
353

354
#### Production Configuration
355

356
```python
357
from poetry.config.config import Config
358

359
def setup_production_config():
360
    """Configure Poetry for production deployment."""
361
    config = Config.create()
362
    
363
    # Production-optimized settings
364
    config.merge({
365
        "virtualenvs.create": False,         # Use system Python
366
        "installer.max-workers": 4,          # Parallel installation
367
        "installer.modern-installation": True, # Modern resolver
368
        "cache-dir": "/opt/poetry/cache"     # System cache
369
    })
370
    
371
    return config
372
```
373

374
## Error Handling
375

376
Configuration-related exceptions and error conditions:
377

378
```python { .api }
379
class ConfigurationError(PoetryError):
380
    """Configuration-related errors."""
381

382
class InvalidConfigurationError(ConfigurationError):
383
    """Invalid configuration values or format."""
384

385
class ConfigurationFileError(ConfigurationError):
386
    """Configuration file reading/writing errors."""
387
```
388

389
Common configuration errors:
390
- Invalid configuration file format
391
- Missing required authentication credentials
392
- Invalid repository URLs
393
- Conflicting configuration values
394
- Permission errors accessing configuration files