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

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

在 Python 开发中，虚拟环境是隔离项目依赖的关键工具。传统工具如 venv 和 virtualenv 往往存在创建速度慢、版本管理繁琐等问题。uv 作为一款用 Rust 编写的极速 Python 包管理器，提供了更高效的解决方案。它能自动下载并管理 Python 解释器，无缝集成包管理，显著提升了环境一致性和版本控制的效率。

安装 uv

开始之前，先确保系统已安装 uv。不同操作系统的安装方式略有差异：

Linux 和 macOS

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

安装完成后，运行以下命令验证版本：

uv --version

创建虚拟环境

使用 uv venv 命令即可快速初始化环境，默认会在当前目录生成 .venv 文件夹。

基础用法

uv venv

这条命令会创建一个包含特定 Python 解释器和基本依赖管理工具的独立目录。

指定名称或路径

如果不想使用默认的 .venv，可以自定义名称或路径：

uv venv myenv              # 创建名为 myenv 的环境
uv venv ../path/to/env     # 在指定父路径下创建

指定 Python 版本

这是 uv 的一大亮点。如果系统中没有所需版本，它会自动下载。支持多种格式：

uv venv --python 3.11                 # 使用 Python 3.11
uv venv --python 3.12.3               # 指定具体补丁版本
uv venv --python ">=3.10,<3.13"      # 使用版本范围
uv venv --python [email protected]         # 指定实现和版本

支持的格式包括 <version>（如 3.12）、<version-specifier>（如 >=3.12）以及实现标识符（如 cpython、pypy）。例如，使用 PyPy 只需：

uv venv --python pypy

激活虚拟环境

创建后需要激活才能使用其中的 Python 和 pip。激活后终端提示符通常会显示环境名称。

Linux 和 macOS

根据使用的 Shell 选择对应的激活脚本：

# Bash / Zsh
source .venv/bin/activate

# Fish
source .venv/bin/activate.fish

# Csh / Tcsh
source .venv/bin/activate.csh

# Nushell
use .venv/bin/activate.nu

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 开发者的首选工具。