uv 虚拟环境管理实战：venv 创建、激活与版本指定

Windows

# Command Prompt
.venv\Scripts\activate.bat

# PowerShell
.venv\Scripts\Activate.ps1

退出环境时，所有平台通用：

deactivate

Python 版本管理技巧

uv 内置了强大的版本管理功能，无需手动配置复杂的解释器路径。

查看与安装版本

列出 uv 支持的所有可用版本：

uv python list
uv python list 3.12   # 查看特定系列

预先安装特定版本（而非创建环境时自动下载）：

uv python install 3.11.6
uv python install pypy

升级与偏好设置

支持将已安装的 Python 升级到最新补丁版本（预览特性）：

uv python upgrade 3.12

通过配置文件控制 uv 对系统 Python 的偏好：

# 优先使用系统 Python
uv config set python-preference system

# 仅使用 uv 管理的 Python
uv venv --no-managed-python

可选偏好包括 managed（默认）、only-managed、system 和 only-system。

高级用法与自动化

自动发现与运行

即使不显式激活，uv run 也能自动在当前目录或其父目录的 .venv 中运行脚本：

uv run python script.py
uv run pip list

配合 --project 参数可指定项目根目录：

uv --project /path/to/project run python script.py

配置文件

在项目根目录创建 uv.toml 可实现持久化配置：

[python]
default-version = "3.12"
preference = "managed"
downloads = "automatic"

[venv]
directory = ".venv"
auto-activate = false

此外，.python-version 文件也能固定项目所需的 Python 版本，uv 读取该文件后会自动匹配对应环境。

缓存管理

uv 会缓存下载的 Python 版本和包以提升速度：

uv cache dir          # 查看缓存位置
uv cache clean        # 清理全部缓存
uv cache clean --python # 仅清理 Python 版本

常见问题排查

问题：创建环境时报 Python 版本未找到。

• 检查列表：uv python list
• 允许自动下载：uv venv --python 3.12 --allow-downloads
• 手动安装：uv python install 3.12

问题：IDE 无法识别虚拟环境。

• 确保 IDE 指向的是虚拟环境内的解释器路径（如 ./.venv/bin/python）。
• VS Code 可通过命令面板选择解释器：Python: Select Interpreter。
• PyCharm 在设置中添加现有环境路径。

问题：激活脚本失效。

• 确认使用了正确的 Shell 脚本（如 zsh 需 activate，fish 需 activate.fish）。
• 尝试更新 shell 集成：uv tool update-shell。
• 临时手动添加 PATH：export PATH="./.venv/bin:$PATH"。

掌握这些核心命令和配置，就能高效地利用 uv 管理多项目环境，彻底告别依赖冲突和版本混乱。随着 uv 生态的完善，它正逐渐成为 Python 开发者的首选工具。