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

选择 Python 实现

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

uv venv --python pypy
uv venv --python [email protected]
uv venv --python cp311

激活虚拟环境

创建虚拟环境后，需要激活它才能使用。激活虚拟环境会将当前终端的 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)。

停用虚拟环境

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

deactivate

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

Python 版本管理高级技巧

查看可用 Python 版本

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

uv python list

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

uv python list 3.12
uv python list pypy

安装特定 Python 版本

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

uv python install 3.11.6
uv python install 3.12
uv python install pypy

升级 Python 版本

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

uv python upgrade 3.12
uv python upgrade

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

配置 Python 版本偏好

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

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

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

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

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

指定项目目录

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

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

高级配置与自定义

配置文件

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

[python]
default-version = "3.12"
preference = "managed"
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 版本无法找到的错误。

解决方案：

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 生态中虚拟环境管理的首选工具。