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

支持的 Python 版本格式包括：

• <version> (如 3, 3.12, 3.12.3)
• <version-specifier> (如 >=3.12,<3.13)
• <implementation> (如 cpython 或 cp)
• <implementation>@<version> (如 [email protected])
• <implementation><version> (如 cpython3.12 或 cp312)

选择 Python 实现

uv 支持多种 Python 实现，包括 CPython、PyPy 和 GraalPy。可以通过以下命令指定：

uv venv --python pypy # 使用最新版 PyPy
uv venv --python [email protected] # 指定 GraalPy 版本
uv venv --python cp311 # 使用 CPython 3.11

激活虚拟环境

创建虚拟环境后，需要激活它才能使用。激活虚拟环境会将当前终端的 Python 和 pip 命令指向虚拟环境中的版本。

Linux 和 macOS

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 (CMD)

.venv\Scripts\activate.bat

PowerShell

.venv\Scripts\Activate.ps1

激活成功后，终端提示符会显示虚拟环境的名称，如：

(.venv) user@machine:~$

停用虚拟环境

当需要退出虚拟环境时，可以使用以下命令：

deactivate

这条命令适用于所有支持的 shell 和操作系统。停用后，终端提示符将恢复正常，Python 和 pip 命令将指向系统默认版本。

Python 版本管理高级技巧

查看可用 Python 版本

可以使用以下命令查看 uv 支持的 Python 版本：

uv python list

要查看特定版本系列的可用版本：

uv python list 3.12 # 查看所有 3.12.x 版本
uv python list pypy # 查看所有 PyPy 版本

安装特定 Python 版本

如果需要预先安装特定的 Python 版本（而不是在创建虚拟环境时自动下载），可以使用：

uv python install 3.11.6 # 安装特定版本
uv python install 3.12 # 安装最新的 3.12.x 版本
uv python install pypy # 安装最新的 PyPy 版本

升级 Python 版本

uv 支持升级已安装的 Python 版本到最新的补丁版本：

uv python upgrade 3.12 # 升级 3.12 到最新补丁版本
uv python upgrade # 升级所有已安装的 Python 版本

注意：升级功能目前是预览特性，仅支持 uv 管理的 Python 版本，且不支持 PyPy 和 GraalPy。

配置 Python 版本偏好

可以通过设置 python-preference 配置项来控制 uv 对系统 Python 和 uv 管理的 Python 的偏好：

# 在配置文件中设置
uv config set python-preference system # 优先使用系统 Python
# 或在命令中临时设置
uv venv --python 3.12 --no-managed-python # 仅使用系统 Python

可用的偏好选项：

• managed (默认): 优先使用 uv 管理的 Python
• only-managed: 仅使用 uv 管理的 Python
• system: 优先使用系统 Python
• only-system: 仅使用系统 Python

虚拟环境的自动发现与使用

uv 具有自动发现虚拟环境的能力，这使得在项目间切换更加便捷。

自动发现规则

当运行 uv 命令时，它会按照以下顺序搜索虚拟环境：

1. 激活的虚拟环境（通过 VIRTUAL_ENV 环境变量）
2. 当前目录或父目录中的 .venv 目录
3. 系统 Python 环境（如果使用 --system 标志）

在虚拟环境中运行命令

即使没有显式激活虚拟环境，也可以使用 uv run 命令在虚拟环境中运行 Python 脚本或命令：

uv run python script.py # 在自动发现的虚拟环境中运行脚本
uv run -- python script.py --arg # 传递命令行参数给脚本
uv run pip list # 在虚拟环境中运行 pip 命令

指定项目目录

可以使用 --project 选项指定项目目录，uv 会在该目录及其父目录中搜索虚拟环境：

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

高级配置与自定义

配置文件

uv 的配置可以通过 uv.toml 文件进行自定义。以下是一个与虚拟环境相关的配置示例：

# uv.toml
[python]
# 默认 Python 版本
default-version = "3.12"
# Python 版本偏好
preference = "managed"
# 是否自动下载 Python
downloads = "automatic"

[venv]
# 默认虚拟环境目录
directory = ".venv"
# 是否在创建时自动激活
auto-activate = false

使用 .python-version 文件

可以在项目根目录创建 .python-version 文件，指定项目所需的 Python 版本：

3.12.3

当在该目录下运行 uv venv 时，uv 会自动使用文件中指定的 Python 版本。

虚拟环境的缓存管理

uv 会缓存下载的 Python 版本和包，以提高后续创建虚拟环境的速度。可以使用以下命令管理缓存：

uv cache dir # 显示缓存目录
uv cache clean # 清理所有缓存
uv cache clean --python # 仅清理 Python 版本缓存

常见问题与解决方案

虚拟环境创建失败

问题：创建虚拟环境时遇到 Python 版本无法找到的错误。

解决方案：

1. 检查指定的 Python 版本是否有效：uv python list
2. 允许 uv 自动下载 Python：uv venv --python 3.12 --allow-downloads
3. 手动安装所需 Python 版本：uv python install 3.12

激活脚本问题

问题：在某些 shell 中无法激活虚拟环境。

解决方案：

1. 确保使用了正确的激活脚本（如 zsh 使用 activate，fish 使用 activate.fish）
2. 尝试使用 uv 的 shell 集成：uv tool update-shell
3. 手动将虚拟环境的 bin 目录添加到 PATH：export PATH="./.venv/bin:$PATH"

版本升级问题

问题：无法升级虚拟环境中的 Python 版本。

解决方案：

1. 注意 uv 目前只支持补丁版本的升级（如 3.12.1 到 3.12.2）
2. 对于次要版本升级（如 3.11 到 3.12），需要创建新的虚拟环境
3. 启用 Python 升级预览特性：uv venv --python 3.12 --preview-features python-upgrade

与其他工具的兼容性

问题：uv 创建的虚拟环境与某些 IDE 或工具不兼容。

解决方案：

1. 确保 IDE 使用了虚拟环境中的 Python 解释器路径
2. 在 PyCharm 中：File > Settings > Project: xxx > Python Interpreter > Add > Existing environment
3. 在 VS Code 中：Ctrl+Shift+P > Python: Select Interpreter > 选择 ./.venv/bin/python

总结

uv 提供了一个快速、灵活的虚拟环境管理解决方案，解决了传统工具的诸多痛点。通过本文的介绍，你已经掌握了使用 uv 创建、激活虚拟环境，以及管理 Python 版本的基本方法。

关键知识点回顾

• 使用 uv venv 创建虚拟环境，可指定名称和路径
• 通过 --python 选项灵活指定 Python 版本
• 不同操作系统下的激活命令
• 利用 .python-version 文件实现项目版本固定
• uv run 命令可直接在虚拟环境中运行程序
• 通过配置文件和命令行选项自定义行为

随着 uv 的不断发展，它有望成为 Python 生态中虚拟环境管理的首选工具。