uv 是一款基于 Rust 编写的高性能 Python 包管理器，提供极速的虚拟环境管理能力。详细阐述了利用 uv 创建、激活虚拟环境的具体命令，包括指定 Python 版本、跨平台激活方式及版本管理高级技巧。内容涵盖自动发现规则、配置文件定制、缓存管理及常见问题排查，旨在帮助开发者实现高效的项目环境隔离与依赖管理。
在 Python 开发中，虚拟环境（Virtual Environment）是隔离项目依赖的关键工具。传统工具如 venv 和 virtualenv 存在创建速度慢、版本管理繁琐等问题。uv 作为一款用 Rust 编写的极速 Python 包管理器，提供了更高效的虚拟环境管理方案。本文将详细介绍如何使用 uv 创建、激活虚拟环境，并灵活指定 Python 版本，帮助开发者解决环境一致性和版本控制的痛点。
虚拟环境（Virtual Environment）是一个独立的 Python 运行环境，允许每个项目拥有自己的依赖包，而不会与其他项目冲突。它通过创建一个包含特定 Python 解释器和依赖包的目录，实现项目间的环境隔离。
相比传统的 venv 和 virtualenv，uv 的虚拟环境具有以下优势：
| 特性 | uv | venv | virtualenv |
|---|---|---|---|
| 创建速度 | 极快（Rust 实现） | 较慢 | 中等 |
| Python 版本管理 | 内置支持，可自动下载 | 需要手动指定 | 有限支持 |
| 跨平台兼容性 | 优秀 | 良好 | 良好 |
| 缓存机制 | 有 | 无 | 无 |
| 与包管理集成 | 无缝集成 | 需要单独使用 pip | 需要单独使用 pip |
在开始使用 uv 管理虚拟环境之前，需要先安装 uv。以下是在不同操作系统上的安装方法：
curl -LsSf https://astral.sh/uv/install.sh | sh
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 # 在指定路径创建虚拟环境
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)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 命令指向虚拟环境中的版本。
source .venv/bin/activate
source .venv/bin/activate.fish
source .venv/bin/activate.csh
use .venv/bin/activate.nu
.venv\Scripts\activate.bat
.venv\Scripts\Activate.ps1
.venv\Scripts\Activate.ps1
激活成功后，终端提示符会显示虚拟环境的名称，如：
(.venv) user@machine:~$
当需要退出虚拟环境时，可以使用以下命令：
deactivate
这条命令适用于所有支持的 shell 和操作系统。停用后，终端提示符将恢复正常，Python 和 pip 命令将指向系统默认版本。
可以使用以下命令查看 uv 支持的 Python 版本：
uv python list
要查看特定版本系列的可用版本：
uv python list 3.12 # 查看所有 3.12.x 版本
uv python list pypy # 查看所有 PyPy 版本
如果需要预先安装特定的 Python 版本（而不是在创建虚拟环境时自动下载），可以使用：
uv python install 3.11.6 # 安装特定版本
uv python install 3.12 # 安装最新的 3.12.x 版本
uv python install pypy # 安装最新的 PyPy 版本
uv 支持升级已安装的 Python 版本到最新的补丁版本：
uv python upgrade 3.12 # 升级 3.12 到最新补丁版本
uv python upgrade # 升级所有已安装的 Python 版本
注意：升级功能目前是预览特性，仅支持 uv 管理的 Python 版本，且不支持 PyPy 和 GraalPy。
可以通过设置 python-preference 配置项来控制 uv 对系统 Python 和 uv 管理的 Python 的偏好：
# 在配置文件中设置
uv config set python-preference system # 优先使用系统 Python
# 或在命令中临时设置
uv venv --python 3.12 --no-managed-python # 仅使用系统 Python
可用的偏好选项：
managed (默认): 优先使用 uv 管理的 Pythononly-managed: 仅使用 uv 管理的 Pythonsystem: 优先使用系统 Pythononly-system: 仅使用系统 Pythonuv 具有自动发现虚拟环境的能力，这使得在项目间切换更加便捷。
当运行 uv 命令时，它会按照以下顺序搜索虚拟环境：
VIRTUAL_ENV 环境变量）.venv 目录--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 版本无法找到的错误。
解决方案：
uv python listuv venv --python 3.12 --allow-downloadsuv python install 3.12问题：在某些 shell 中无法激活虚拟环境。
解决方案：
activate，fish 使用 activate.fish）uv tool update-shellexport PATH="./.venv/bin:$PATH"问题：无法升级虚拟环境中的 Python 版本。
解决方案：
uv venv --python 3.12 --preview-features python-upgrade问题：uv 创建的虚拟环境与某些 IDE 或工具不兼容。
解决方案：
./.venv/bin/pythonuv 提供了一个快速、灵活的虚拟环境管理解决方案，解决了传统工具的诸多痛点。通过本文的介绍，你已经掌握了使用 uv 创建、激活虚拟环境，以及管理 Python 版本的基本方法。
uv venv 创建虚拟环境，可指定名称和路径--python 选项灵活指定 Python 版本.python-version 文件实现项目版本固定uv run 命令可直接在虚拟环境中运行程序uv 作为一个活跃开发的项目，未来可能会引入更多虚拟环境相关的特性，如：
随着 uv 的不断发展，它有望成为 Python 生态中虚拟环境管理的首选工具。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online