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

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

引言：虚拟环境管理的痛点与解决方案

在 Python 开发中，虚拟环境（Virtual Environment）是隔离项目依赖的关键工具。传统工具如 venv 和 virtualenv 存在创建速度慢、版本管理繁琐等问题。uv 作为一款用 Rust 编写的极速 Python 包管理器，提供了更高效的虚拟环境管理方案。本文将详细介绍如何使用 uv 创建、激活虚拟环境，并灵活指定 Python 版本。

uv 虚拟环境基础

什么是虚拟环境

虚拟环境（Virtual Environment）是一个独立的 Python 运行环境，允许每个项目拥有自己的依赖包，而不会与其他项目冲突。它通过创建一个包含特定 Python 解释器和依赖包的目录，实现项目间的环境隔离。

uv 虚拟环境的优势

相比传统的 venv 和 virtualenv，uv 的虚拟环境具有以下优势：

特性	uv	venv	virtualenv
创建速度	极快（Rust 实现）	较慢	中等
Python 版本管理	内置支持，可自动下载	需要手动指定	有限支持
跨平台兼容性	优秀	良好	良好
缓存机制	有	无	无
与包管理集成	无缝集成	需要单独使用 pip	需要单独使用 pip

安装 uv

在开始使用 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 创建虚拟环境非常简单，基本命令如下：

uv venv 

这条命令会在当前目录下创建一个名为 .venv 的虚拟环境目录，包含了 Python 解释器和基本的依赖管理工具。

指定虚拟环境名称或路径

默认情况下，uv 会创建名为 .venv 的虚拟环境。如果需要指定其他名称或路径，可以使用以下命令：

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

指定 Python 版本

uv 允许在创建虚拟环境时指定 Python 版本。如果系统中没有所需版本，uv 会自动下载并安装。

uv venv --python 3.11 # 使用 Python 3.11 创建虚拟环境
uv venv --python 3.12.3 # 指定具体的补丁版本
uv venv --python ">=3.10,<3.13" # 使用版本范围

支持的 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 

PowerShell Core

.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 版本并存的高级支持

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