0
# Virtualenv
1

2
A comprehensive tool for creating isolated Python virtual environments that enable developers to manage dependencies and Python versions per project without conflicts. Virtualenv offers command-line functionality for creating, activating, and managing virtual environments with support for different Python interpreters, custom site-packages directories, and environment isolation features.
3

4
## Package Information
5

6
- **Package Name**: virtualenv
7
- **Language**: Python
8
- **Installation**: `pip install virtualenv`
9

10
## Core Imports
11

12
```python
13
import virtualenv
14
```
15

16
For programmatic usage:
17

18
```python
19
from virtualenv import create_environment, main
20
```
21

22
## Basic Usage
23

24
### Command Line Interface
25

26
```bash
27
# Create a virtual environment
28
virtualenv myenv
29

30
# Create with specific Python version
31
virtualenv --python=python3.8 myenv
32

33
# Create with system site-packages access
34
virtualenv --system-site-packages myenv
35

36
# Clear and recreate environment
37
virtualenv --clear myenv
38
```
39

40
### Programmatic Interface
41

42
```python
43
import virtualenv
44

45
# Create a basic virtual environment
46
virtualenv.create_environment('/path/to/myenv')
47

48
# Create with custom options
49
virtualenv.create_environment(
50
    '/path/to/myenv',
51
    site_packages=True,  # Include global site-packages
52
    clear=True,          # Clear existing environment
53
    prompt='myproject',  # Custom prompt
54
    no_pip=False,        # Install pip
55
    no_setuptools=False, # Install setuptools
56
    no_wheel=False,      # Install wheel
57
    symlink=True         # Use symlinks instead of copying
58
)
59
```
60

61
## Architecture
62

63
Virtualenv is designed as a single-module package with the following key components:
64

65
- **Environment Creation**: Core functionality for setting up isolated Python environments
66
- **Platform Detection**: Extensive support for different operating systems and Python implementations
67
- **File Operations**: Utilities for copying, linking, and managing files during environment setup
68
- **Package Management**: Integration with pip, setuptools, and wheel for dependency installation
69
- **Activation Scripts**: Generation of platform-specific activation scripts
70

71
The package provides both command-line and programmatic interfaces, making it suitable for interactive use and integration into automated deployment workflows.
72

73
## Capabilities
74

75
### Environment Creation
76

77
Primary interface for creating and configuring virtual Python environments with extensive customization options including Python interpreter selection, package isolation controls, and dependency management.
78

79
```python { .api }
80
def create_environment(
81
    home_dir,
82
    site_packages=False,
83
    clear=False,
84
    prompt=None,
85
    search_dirs=None,
86
    download=False,
87
    no_setuptools=False,
88
    no_pip=False,
89
    no_wheel=False,
90
    symlink=True
91
):
92
    """
93
    Creates a new environment in home_dir.
94
    
95
    Parameters:
96
    - home_dir (str): Target directory for the virtual environment
97
    - site_packages (bool): Include global site-packages in environment
98
    - clear (bool): Clear existing environment before creating
99
    - prompt (str): Custom prompt prefix for the environment
100
    - search_dirs (list): Directories to search for packages
101
    - download (bool): Download packages if not found locally
102
    - no_setuptools (bool): Skip installing setuptools
103
    - no_pip (bool): Skip installing pip
104
    - no_wheel (bool): Skip installing wheel
105
    - symlink (bool): Use symlinks instead of copying files
106
    
107
    Returns:
108
    None
109
    """
110

111
def main():
112
    """
113
    Command-line interface entry point.
114
    
115
    Parses command-line arguments and creates virtual environment
116
    based on provided options. Uses sys.argv for argument parsing.
117
    
118
    Returns:
119
    None (exits process)
120
    """
121
```
122

123
[Environment Creation](./environment-creation.md)
124

125
### Utility Functions
126

127
Helper functions for path resolution, file system operations, and environment introspection that support the core virtualenv functionality.
128

129
```python { .api }
130
def path_locations(home_dir, dry_run=False):
131
    """
132
    Calculate standard path locations for a virtual environment.
133
    
134
    Parameters:
135
    - home_dir (str): Virtual environment directory
136
    - dry_run (bool): Whether this is a dry run
137
    
138
    Returns:
139
    tuple: (home_dir, lib_dir, inc_dir, bin_dir)
140
    """
141

142
def is_executable_file(fpath):
143
    """
144
    Check if a file path is an executable file.
145
    
146
    Parameters:
147
    - fpath (str): File path to check
148
    
149
    Returns:
150
    bool: True if file exists and is executable
151
    """
152

153
def resolve_interpreter(exe):
154
    """
155
    Resolve Python interpreter path from name or path.
156
    
157
    Parameters:
158
    - exe (str): Python executable path or name
159
    
160
    Returns:
161
    str: Resolved absolute path to interpreter
162
    """
163
```
164

165
[Utility Functions](./utility-functions.md)
166

167
### File Operations
168

169
Comprehensive file and directory manipulation functions for environment setup, including copying, linking, and permission management with cross-platform compatibility.
170

171
```python { .api }
172
def copy_file_or_folder(src, dest, symlink=True):
173
    """
174
    Copy file or folder with symlink support.
175
    
176
    Parameters:
177
    - src (str): Source path
178
    - dest (str): Destination path
179
    - symlink (bool): Use symlinks when possible
180
    
181
    Returns:
182
    None
183
    """
184

185
def mkdir(at_path):
186
    """
187
    Create directory if it doesn't exist.
188
    
189
    Parameters:
190
    - at_path (str): Directory path to create
191
    
192
    Returns:
193
    None
194
    """
195

196
def rm_tree(folder):
197
    """
198
    Remove directory tree recursively.
199
    
200
    Parameters:
201
    - folder (str): Directory path to remove
202
    
203
    Returns:
204
    None
205
    """
206
```
207

208
[File Operations](./file-operations.md)
209

210
## Classes
211

212
### Logger
213

214
```python { .api }
215
class Logger:
216
    """
217
    Logging object for command-line script with level-based output control.
218
    
219
    Class Constants:
220
    - DEBUG: Debug level messages
221
    - INFO: Informational messages  
222
    - NOTIFY: Important notifications (between INFO and WARN)
223
    - WARN/WARNING: Warning messages
224
    - ERROR: Error messages
225
    - FATAL: Fatal error messages
226
    
227
    Methods:
228
    - debug(msg, *args, **kw): Log debug message
229
    - info(msg, *args, **kw): Log info message
230
    - notify(msg, *args, **kw): Log notification message
231
    - warn(msg, *args, **kw): Log warning message
232
    - error(msg, *args, **kw): Log error message
233
    - fatal(msg, *args, **kw): Log fatal message
234
    - start_progress(msg): Start progress indicator
235
    - end_progress(msg): End progress indicator
236
    """
237

238
class ConfigOptionParser:
239
    """
240
    Extended OptionParser with configuration file support.
241
    
242
    Inherits from optparse.OptionParser and adds ability to read
243
    configuration from INI files and environment variables.
244
    """
245

246
class FileView:
247
    """
248
    File viewing utility for binary file operations.
249
    
250
    Provides windowed access to file contents for reading and
251
    modifying specific portions of binary files.
252
    """
253
```
254

255
## Constants and Configuration
256

257
### Version Information
258

259
```python { .api }
260
__version__: str  # Package version string ("16.7.11" - note: differs from package tag)
261
virtualenv_version: str  # Legacy alias for __version__
262
```
263

264
### Platform Detection
265

266
```python { .api }
267
IS_WIN: bool  # True if running on Windows
268
IS_CYGWIN: bool  # True if running on Cygwin
269
IS_DARWIN: bool  # True if running on macOS
270
IS_PYPY: bool  # True if running on PyPy interpreter
271
VERSION: str  # Current Python version (e.g., "3.8.10")
272
PY_VERSION: str  # Python version with prefix (e.g., "python3.8")
273
```
274

275
### Directory Configuration
276

277
```python { .api }
278
DEFAULT_STORAGE_DIR: str  # Default storage directory for virtualenv files
279
DEFAULT_CONFIG_FILE: str  # Path to default configuration file
280
USER_DIR: str  # User's home directory
281
```