0
# Virtual Environment Management
1

2
UV provides fast virtual environment creation and management with automatic Python version selection, efficient package installations, and seamless integration with project workflows. Virtual environments are automatically discovered and activated when working with UV projects.
3

4
## Capabilities
5

6
### Virtual Environment Creation
7

8
Create virtual environments with automatic Python version selection and optimal configuration for performance and compatibility.
9

10
```bash { .api }
11
uv venv [PATH]
12
# Creates a virtual environment
13
# Default path is .venv in current directory
14

15
# Aliases:
16
# uv virtualenv [PATH]
17
# uv v [PATH]
18

19
# Options:
20
# --python VERSION        # Python version to use
21
# --system-site-packages  # Give access to system packages
22
# --seed                 # Install seed packages (pip, setuptools)
23
# --relocatable          # Make environment relocatable
24
# --prompt PROMPT        # Set environment prompt
25
# --clear               # Clear existing environment
26
# --symlinks            # Use symlinks instead of copies
27
# --copies              # Use copies instead of symlinks
28
```
29

30
Usage examples:
31

32
```bash
33
# Create virtual environment in .venv
34
uv venv
35

36
# Create in specific directory
37
uv venv myproject-env
38

39
# Create with specific Python version
40
uv venv --python 3.12
41

42
# Create with system packages access
43
uv venv --system-site-packages
44

45
# Create with custom prompt
46
uv venv --prompt "MyProject"
47

48
# Clear and recreate existing environment
49
uv venv --clear
50
```
51

52
### Environment Discovery
53

54
UV automatically discovers virtual environments using a hierarchical search strategy that prioritizes project-specific environments.
55

56
Discovery order:
57
1. **Active environment**: Currently activated virtual environment
58
2. **Project environment**: `.venv` directory in current or parent directories
59
3. **Custom environment**: `UV_PROJECT_ENVIRONMENT` environment variable location
60
4. **Conda environments**: Active conda environments when detected
61

62
Environment variables:
63
```bash { .api }
64
UV_PROJECT_ENVIRONMENT=env_name    # Custom environment name/path
65
VIRTUAL_ENV=/path/to/env          # Currently active environment
66
CONDA_DEFAULT_ENV=env_name        # Active conda environment
67
```
68

69
### Environment Activation
70

71
While UV automatically uses discovered environments, manual activation is still supported for shell integration:
72

73
```bash { .api }
74
# Bash/Zsh activation
75
source .venv/bin/activate
76

77
# Windows activation
78
.venv\Scripts\activate
79

80
# Fish shell
81
source .venv/bin/activate.fish
82

83
# PowerShell
84
.venv\Scripts\Activate.ps1
85
```
86

87
UV commands automatically use the discovered environment without requiring activation:
88

89
```bash
90
# These commands automatically use .venv if present:
91
uv pip install requests
92
uv pip list
93
uv run python script.py
94
```
95

96
### Environment Configuration
97

98
Configure virtual environment behavior through UV settings and project configuration.
99

100
Global configuration in `uv.toml`:
101
```toml { .api }
102
[tool.uv]
103
# Virtual environment settings
104
project-environment = ".venv"      # Default environment name
105
python-preference = "managed"      # Python selection preference
106
seed-packages = true               # Install seed packages by default
107

108
# Environment creation settings
109
venv-symlinks = true              # Use symlinks (Unix)
110
venv-system-site-packages = false # System packages access
111
```
112

113
Project-specific configuration in `pyproject.toml`:
114
```toml { .api }
115
[tool.uv]
116
# Project environment settings
117
virtual-env = ".venv"             # Virtual environment path
118
python = "3.12"                   # Required Python version
119

120
# Workspace settings for monorepos
121
[tool.uv.workspace]
122
virtual-env = ".venv"             # Shared workspace environment
123
```
124

125
### Environment Management
126

127
UV provides utilities for managing and inspecting virtual environments.
128

129
```bash { .api }
130
# Show environment information
131
python -m site                   # Show Python paths
132
python -c "import sys; print(sys.prefix)"  # Show environment path
133

134
# Environment inspection
135
uv pip list                      # List installed packages
136
uv pip show package             # Show package details
137
uv pip freeze                   # Export environment state
138
```
139

140
### Environment Migration
141

142
Migrate between virtual environments or recreate environments:
143

144
```bash
145
# Export current environment
146
uv pip freeze > requirements.txt
147

148
# Create new environment
149
uv venv new-env --clear
150

151
# Install packages in new environment
152
uv pip install -r requirements.txt
153

154
# Update project to use new environment
155
mv new-env .venv
156
```
157

158
### Environment Cleanup
159

160
Remove virtual environments and clean up associated resources:
161

162
```bash { .api }
163
# Remove virtual environment directory
164
rm -rf .venv
165

166
# Or on Windows:
167
rmdir /s .venv
168

169
# Recreate clean environment
170
uv venv --clear
171
```
172

173
## Environment Structure
174

175
UV virtual environments follow standard Python virtual environment structure:
176

177
```text { .api }
178
.venv/
179
├── bin/                    # Executables (Unix)
180
│   ├── activate           # Activation script
181
│   ├── python            # Python interpreter symlink
182
│   ├── pip               # Package installer
183
│   └── uv                # UV executable (if installed)
184
├── Scripts/               # Executables (Windows)
185
│   ├── activate.bat      # Activation script
186
│   ├── python.exe       # Python interpreter
187
│   └── pip.exe          # Package installer
188
├── include/              # Header files
189
├── lib/                  # Installed packages (Unix)
190
│   └── python3.x/
191
│       └── site-packages/
192
├── Lib/                  # Installed packages (Windows)
193
│   └── site-packages/
194
└── pyvenv.cfg           # Environment configuration
195
```
196

197
## Environment Configuration Files
198

199
Virtual environments use configuration files to define behavior:
200

201
### pyvenv.cfg
202
```ini { .api }
203
home = /usr/bin
204
include-system-site-packages = false
205
version = 3.12.1
206
executable = /usr/bin/python3.12
207
command = /usr/bin/python3.12 -m venv .venv
208
```
209

210
### activate script behavior
211
The activation script modifies the shell environment:
212
- Prepends virtual environment bin directory to PATH
213
- Sets VIRTUAL_ENV environment variable
214
- Updates PS1 prompt to show environment name
215
- Provides deactivate function to restore original environment
216

217
## Performance Optimizations
218

219
UV optimizes virtual environment operations:
220

221
- **Fast creation**: Leverages symlinks and efficient Python detection
222
- **Cached downloads**: Reuses downloaded packages across environments
223
- **Parallel operations**: Installs packages concurrently when possible
224
- **Smart linking**: Uses hardlinks when safe, symlinks when beneficial
225

226
## Platform-Specific Considerations
227

228
### Unix/Linux/macOS
229
- Uses symlinks by default for Python interpreter and libraries
230
- Activation script modifies PATH and environment variables
231
- Supports multiple Python installations and versions
232

233
### Windows
234
- Uses copies instead of symlinks for compatibility
235
- Provides batch and PowerShell activation scripts
236
- Integrates with Windows registry Python installations
237

238
### Conda Integration
239
UV recognizes and works with conda environments:
240
- Detects active conda environments
241
- Respects conda environment paths
242
- Allows UV operations within conda environments
243

244
## Environment Best Practices
245

246
1. **Project isolation**: Use one virtual environment per project
247
2. **Version control**: Add `.venv/` to `.gitignore`
248
3. **Documentation**: Include environment recreation instructions
249
4. **Dependency tracking**: Use `requirements.txt` or `pyproject.toml`
250
5. **Clean environments**: Recreate environments periodically
251
6. **Path management**: Avoid hardcoded paths to environment
252

253
## Troubleshooting
254

255
Common virtual environment issues and solutions:
256

257
### Environment not found
258
```bash
259
# Check current directory and parents for .venv
260
ls -la .venv
261
find . -name ".venv" -type d
262

263
# Create environment if missing
264
uv venv
265
```
266

267
### Wrong Python version
268
```bash
269
# Check Python version in environment
270
.venv/bin/python --version
271

272
# Recreate with specific Python
273
uv venv --python 3.12 --clear
274
```
275

276
### Package installation failures
277
```bash
278
# Check environment permissions
279
ls -la .venv/
280

281
# Recreate environment
282
uv venv --clear
283

284
# Use system packages if needed
285
uv venv --system-site-packages
286
```
287

288
### PATH issues
289
```bash
290
# Check if environment is in PATH
291
echo $PATH | grep .venv
292

293
# Activate environment manually
294
source .venv/bin/activate
295

296
# Or use UV commands directly
297
uv pip install package
298
```
299

300
## Integration with IDE and Tools
301

302
Popular development environments integrate with UV virtual environments:
303

304
- **VS Code**: Automatically detects `.venv` environments
305
- **PyCharm**: Configure interpreter to use `.venv/bin/python`
306
- **Vim/Neovim**: Use environment-specific Python for language servers
307
- **Jupyter**: Install `ipykernel` and register environment as kernel
308
- **Git hooks**: Use environment Python in pre-commit configurations