使用 uv 管理 Python 虚拟环境：现代 Python 开发的高效实践

目录

• • 前言
  • [1 初识 uv：概述与核心优势](#1 初识 uv：概述与核心优势)
  • • [1.1 什么是 uv](#1.1 什么是 uv)
    • [1.2 uv 的核心优势](#1.2 uv 的核心优势)
  • [2 安装与配置 uv](#2 安装与配置 uv)
  • • [2.1 安装方法](#2.1 安装方法)
    • [2.2 验证安装与常用命令](#2.2 验证安装与常用命令)
  • [3 管理 Python 版本](#3 管理 Python 版本)
  • • [3.1 安装与管理 Python 版本](#3.1 安装与管理 Python 版本)
    • [3.2 在项目中固定 Python 版本](#3.2 在项目中固定 Python 版本)
  • [4 虚拟环境管理](#4 虚拟环境管理)
  • • [4.1 创建虚拟环境](#4.1 创建虚拟环境)
    • [4.2 激活与使用虚拟环境](#4.2 激活与使用虚拟环境)
    • [4.3 uv 的环境发现机制](#4.3 uv 的环境发现机制)
  • [5 项目管理与依赖管理](#5 项目管理与依赖管理)
  • • [5.1 初始化新项目](#5.1 初始化新项目)
    • [5.2 核心文件说明](#5.2 核心文件说明)
    • [5.3 添加与管理依赖](#5.3 添加与管理依赖)
    • [5.4 环境同步](#5.4 环境同步)
  • [6 运行脚本与工具管理](#6 运行脚本与工具管理)
  • • [6.1 运行脚本](#6.1 运行脚本)
    • [6.2 管理 CLI 工具](#6.2 管理 CLI 工具)
  • [7 pip 兼容命令与迁移](#7 pip 兼容命令与迁移)
  • • [7.1 使用 uv 替代 pip](#7.1 使用 uv 替代 pip)
    • [7.2 命令对照表](#7.2 命令对照表)
    • [7.3 迁移现有项目](#7.3 迁移现有项目)
  • [8 常用命令速查](#8 常用命令速查)
  • 结语
  • 参考资料

前言

在 Python 开发领域，包管理和环境管理一直是开发者日常工作中最频繁且最令人头疼的环节。传统的 pip + virtualenv 组合虽然经典，但在面对大型项目或需要快速迭代的场景时，往往显得力不从心------依赖安装速度慢、版本锁定不够可靠、多工具切换繁琐等问题一直困扰着开发者。Astral 团队推出的 uv 正是为解决这些问题而生。

作为一款用 Rust 编写的极速 Python 包和项目管理器，uv 集成了虚拟环境创建、依赖管理、Python 版本管理、项目初始化等多项功能，堪称 Python 生态中的"全能选手"。本文将系统介绍 uv 的核心概念、安装方法、虚拟环境管理以及项目开发实战，帮助读者快速掌握这一现代 Python 开发利器。

1 初识 uv：概述与核心优势

1.1 什么是 uv

uv 是由 Astral 公司（ Ruff linter 的开发团队）推出的一款基于 Rust 编写的 Python 包管理工具，旨在成为"Python 的 Cargo"。它通过一套精心设计的命令集，将 Python 开发中的包管理、环境隔离、项目构建等繁琐任务变得简单而高效。与其他 Python 包管理工具相比，uv 更像是一个全能选手，能够替代 pip、pip-tools、pipx、poetry、pyenv、virtualenv、twine 等多种传统工具。

uv 的核心设计理念是用单一工具覆盖 Python 项目开发的完整生命周期，从 Python 解释器的安装管理，到虚拟环境的创建，再到依赖的添加删除和版本锁定，最后到项目的打包发布，全部可以通过 uv 命令完成。

1.2 uv 的核心优势

uv 在性能、兼容性和功能上都有出色表现，其核心优势主要体现在以下几个方面。

性能卓越 ：uv 使用 Rust 编写，通过激进缓存、并行下载和高效的依赖解析算法，实现了令人惊叹的执行速度。在创建虚拟环境方面，uv 比传统的 python -m venv 快约 56 倍；在安装依赖时，从温缓存安装 23 个包，uv 仅需 0.15 秒，而 pip 需要 6.6 秒，速度提升约 44 倍。这种速度优势在日常开发和 CI/CD 场景中都极具价值。

多功能集成：uv 不只是一个快速的包安装器，更是一个集包管理、虚拟环境、项目管理、CLI 工具安装于一体的综合性工具链。使用 uv，开发者无需再组合使用 pyenv 管理 Python 版本、virtualenv 创建虚拟环境、pip-tools 锁定依赖、pipx 安装 CLI 工具等多种工具，一套命令走天下。

开发体验 ：uv 借鉴了 Node.js 和 Rust 的依赖管理方式，提供了类似 npm install 和 cargo add 的直观命令。项目结构清晰，依赖声明和版本锁定由工具自动管理，让开发者能够专注于业务代码而非环境配置。

向后兼容 ：使用 uv 创建的项目仍然兼容 pip 和其他 Python 工具。uv 使用标准的 pyproject.toml 进行配置，生成的 uv.lock 锁文件遵循跨平台规范，可以与团队中未使用 uv 的成员无缝协作。

2 安装与配置 uv

2.1 安装方法

uv 的安装非常简单，支持多种安装方式。以下是官方推荐的安装方法。

Linux 和 macOS 系统，可以使用官方提供的安装脚本，通过 curl 执行一键安装：

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

Windows 系统，可以在 PowerShell 中执行以下命令完成安装：

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

除了官方安装脚本外，还可以使用 Homebrew 包管理器进行安装（适用于 macOS 和 Linux）：

brew install uv

如果系统中已经安装了 Python，也可以直接使用 pip 安装 uv：

pip install uv

2.2 验证安装与常用命令

安装完成后，可以通过以下命令验证 uv 是否安装成功以及查看版本信息：

uv --version

更新 uv 到最新版本可以使用 uv self update 命令：

uv self update

当需要查看帮助信息时，可以使用 uv help 命令。如果不指定具体命令，它会列出所有可用的顶级命令；如果指定了子命令，则会显示该命令的详细参数说明：

uv help
uv help add

3 管理 Python 版本

3.1 安装与管理 Python 版本

uv 的一大亮点是内置了 Python 版本管理功能，无需单独安装 pyenv 即可管理多个 Python 版本。使用 uv python install 命令可以安装指定版本的 Python：

uv python install 3.12
uv python install 3.13

如果要同时安装多个版本，可以在命令中列出所有需要的版本号：

uv python install 3.11 3.12 3.13

查看已安装的 Python 版本列表，可以使用 uv python list 命令：

uv python list

该命令会显示所有已安装的 Python 版本及其路径信息。值得注意的是，uv 使用预编译的二进制文件分发 Python，相比从源码编译的 pyenv，安装速度大大提升，通常只需几秒钟即可完成。

3.2 在项目中固定 Python 版本

在项目中使用 uv python pin 命令可以将项目固定到特定 Python 版本：

uv python pin 3.12

该命令会在项目中创建 .python-version 文件，后续执行 uv sync 或 uv run 时，uv 会自动使用该版本或在需要时自动下载安装。

4 虚拟环境管理

4.1 创建虚拟环境

虚拟环境是 Python 项目隔离的基石。uv 的虚拟环境管理命令既强大又直观，无需再混合使用 python -m venv 和 source activate 等命令。

创建虚拟环境的基本命令是 uv venv，默认情况下会在当前目录下创建 .venv 目录：

uv venv

如果需要指定虚拟环境的路径或名称，可以使用 --path 或 --name 参数：

uv venv --name my-env --path ~/envs/my-env

创建时指定 Python 版本，只需使用 --python 参数：

uv venv --python 3.11

提示：如果指定的 Python 版本尚未安装，uv 会自动下载并安装该版本。

4.2 激活与使用虚拟环境

创建虚拟环境后，在 POSIX 系统（Linux/macOS）上激活环境的命令如下：

source .venv/bin/activate

在 Windows PowerShell 中，激活命令为：

.venv\Scripts\activate

其他 Shell 的激活脚本路径可参考下表。

Shell	激活脚本
fish	.venv/bin/activate.fish
csh/tcsh	.venv/bin/activate.csh
Nushell	.venv\Scripts\activate.nu

使用 deactivate 命令可以退出当前虚拟环境：

deactivate

4.3 uv 的环境发现机制

uv 在执行包管理命令时，会按照一定顺序自动发现虚拟环境。首先查找通过 VIRTUAL_ENV 环境变量激活的虚拟环境，然后查找 Conda 环境（通过 CONDA_PREFIX），最后在当前目录或最近的父目录中查找 .venv 目录。如果未找到任何环境，uv 会提示创建新环境或使用 --system 参数安装到系统 Python。

使用 VIRTUAL_ENV 环境变量指定环境的方式：

VIRTUAL_ENV=/path/to/venv uv pip install ruff

5 项目管理与依赖管理

5.1 初始化新项目

使用 uv init 命令可以快速初始化一个新的 Python 项目：

uv init my-project

初始化后，uv 会自动生成项目的基本文件结构，包括 .gitignore、.python-version、pyproject.toml、README.md 以及一个示例 Python 文件。需要注意的是，uv init 默认会初始化 Git 仓库。

初始化库项目（而非应用程序项目）可以使用 --lib 参数：

uv init --lib my-package

5.2 核心文件说明

uv 项目中有两个核心文件需要特别关注：pyproject.toml 和 uv.lock。

pyproject.toml 是项目配置文件，用于声明项目的元数据、依赖和构建配置。该文件遵循 PEP 621 规范，是 Python 生态的事实标准。

uv.lock 是自动生成的锁文件，记录了所有直接依赖和间接依赖的确切版本号。这个文件不应手动编辑，只由 uv 工具自动维护。建议将 uv.lock 纳入版本控制，以确保所有开发者和部署环境使用完全一致的依赖版本。

5.3 添加与管理依赖

添加依赖是日常开发中最频繁的操作之一。使用 uv add 命令可以方便地添加包依赖：

uv add requests

添加指定版本的依赖：

uv add requests==2.31.0

添加开发依赖可以使用 --dev 参数：

uv add --dev pytest

使用 --group 参数可以区分不同环境的依赖：

uv add --group dev pytest
uv add --group production gunicorn

删除依赖使用 uv remove 命令，该命令会自动清理相关的传递依赖：

uv remove requests

5.4 环境同步

创建或修改依赖后，需要执行 uv sync 命令同步环境。该命令会自动完成以下操作：检查 Python 版本 → 创建或更新虚拟环境 → 生成或更新 uv.lock → 安装所有依赖。

uv sync

如果只想按照锁文件安装（不更新锁文件），可以使用 --locked 参数：

uv sync --locked

在 CI/CD 环境中，使用 --frozen 参数可以确保严格按锁文件安装：

uv sync --frozen

6 运行脚本与工具管理

6.1 运行脚本

使用 uv run 命令可以直接在项目环境中运行脚本，无需先激活虚拟环境：

uv run python main.py

首次运行 uv run 时，如果环境中尚未创建虚拟环境，uv 会自动完成 Python 版本选择、虚拟环境创建、uv.lock 生成以及依赖安装等一系列准备工作。

uv 还支持 PEP 723 规范的内联依赖脚本。在脚本开头以特殊注释形式声明依赖，运行时 uv 会自动管理：

# /// script
# dependencies = ["requests", "rich"]
# requires-python = ">=3.11"
# ///

import requests
from rich import print

response = requests.get("https://api.github.com/zen")
print(response.text)

6.2 管理 CLI 工具

uv 提供了两种使用 CLI 工具的方式。对于偶尔使用的工具，可以使用 uvx 命令（相当于 uv tool run）在临时隔离环境中运行，无需永久安装：

uvx ruff check .
uvx black --check .

如果需要长期使用某个工具，可以使用 uv tool install 命令将其安装到全局工具目录：

uv tool install ruff

升级已安装的工具可以使用 uv tool upgrade 命令：

uv tool upgrade ruff
uv tool upgrade --all

7 pip 兼容命令与迁移

7.1 使用 uv 替代 pip

对于习惯使用 pip 的开发者，uv 提供了完全兼容的命令接口，只需在原有命令前加上 uv pip 前缀即可。例如：

uv pip install flask requests
uv pip install -r requirements.txt
uv pip uninstall flask

使用 uv pip compile 命令可以编译依赖（相当于 pip-tools 的 pip-compile），生成锁定的 requirements 文件：

uv pip compile requirements.in -o requirements.txt

使用 uv pip sync 命令可以按照 requirements 文件同步环境：

uv pip sync requirements.txt

7.2 命令对照表

为方便从传统工具迁移到 uv，以下列出主要命令的对照关系。

pip/virtualenv 命令	uv 等价命令	说明
python -m venv .venv	uv venv	创建虚拟环境
pip install package	uv add package	安装包并更新项目文件
pip install -r requirements.txt	uv pip install -r requirements.txt	从 requirements 文件安装
pip freeze > requirements.txt	uv export -o requirements.txt	导出依赖到文件
pip list	uv pip list	列出已安装的包
pip uninstall package	uv remove package	卸载包
pyenv install 3.12	uv python install 3.12	安装 Python 版本
pipx install tool	uv tool install tool	安装 CLI 工具
poetry init	uv init	初始化项目
poetry add package	uv add package	添加依赖
poetry sync	uv sync	同步环境

7.3 迁移现有项目

将现有项目迁移到使用 uv 管理非常简单，只需以下几步即可完成。

首先，在项目目录下初始化 uv 项目（如果项目已有 pyproject.toml 可以跳过）：

uv init

然后，同步环境安装所有依赖：

uv sync

之后，就可以使用 uv 的所有命令来管理项目了。原项目的 requirements.txt 文件仍然可以使用 uv pip install -r requirements.txt 来安装，迁移过程非常平滑。

8 常用命令速查

为方便日常使用，将本文中涉及的主要命令整理如下。

命令	作用
uv --version	查看 uv 版本
uv self update	更新 uv 到最新版本
uv help	查看帮助信息
uv python install 3.12	安装指定版本的 Python
uv python list	列出已安装的 Python 版本
uv python pin 3.12	固定项目使用 Python 3.12
uv venv	创建虚拟环境
uv venv --python 3.11	创建基于 Python 3.11 的虚拟环境
uv init my-project	初始化新项目
uv add package	添加依赖
uv add --dev pytest	添加开发依赖
uv add --group prod package	添加生产环境依赖
uv remove package	移除依赖
uv sync	同步环境
uv run python script.py	运行脚本
uv pip install package	使用 pip 兼容方式安装包
uv pip compile requirements.in -o requirements.txt	编译依赖文件
uv tool install ruff	安装 CLI 工具
uvx ruff check .	临时运行 CLI 工具
uv format	格式化代码
uv check	检查项目依赖

结语

uv 通过一套精心设计的命令集，将 Python 开发的包管理、环境隔离、项目构建等繁琐任务变得简单而高效。其核心优势在于极致的速度和一体化的体验。从 uv add 管理依赖到 uv venv 管理环境，从 uv run 无缝执行脚本到 uv tool install 安装 CLI 工具，uv 覆盖了现代 Python 开发的全链路。

无论你是处理大型 Python 项目的资深工程师，还是刚刚开始学习 Python 的新手，将 uv 纳入工具链都将显著提升开发效率和体验。uv 的设计哲学体现了现代开发工具的趋势：用更少的工具、做更多的事、达到更高的效率。现在就开始探索 uv，打造你更流畅的 Python 工作流吧。

参考资料

1 uv 官方文档：https://docs.astral.sh/uv/

2 Astral 官网：https://astral.sh/

3 AppSignal Blog - Switching from Pip to uv in Python: A Comprehensive Guide：https://blog.appsignal.com/2025/09/24/switching-from-pip-to-uv-in-python-a-comprehensive-guide.html

4 博客园 - 从入门到精通：UV 现代 Python 包管理器全命令详解与实战指南：https://www.cnblogs.com/ljbguanli/p/19752560

5 博客园 - Python包管理不再头疼：uv工具快速上手：https://www.cnblogs.com/wang_yb/p/18635441

6 pydevtools - uv: A Complete Guide to Python's Fastest Package Manager：https://pydevtools.com/handbook/explanation/uv-complete-guide