【一起学 Python】补充篇:UV 工具介绍与使用

uv 是一个用 Rust 编写的极快的 Python 包和项目管理器，由 Astral 团队开发（同样开发了 Ruff）。它旨在替代 pip、pip-tools、poetry、pyenv 等工具，提供统一且高性能的解决方案。

我先回顾一下【一起学Python】第4天：无网络离线环境开发python 安装依赖解决方案中讲到的pip，今天我们新学习一个 Python 包管理工具-uv.

🚀 主要特点

极快的速度 – 比 pip 快 10-100 倍
统一工具 – 集成包管理、虚拟环境、项目管理于一体
兼容性好 – 完全兼容 pip 生态系统
跨平台 – 支持 Windows、macOS、Linux
零依赖 – 单个可执行文件，无需 Python 环境

📦 安装

Linux/macOS

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

Windows

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

使用 pip 安装

pip install uv

常用命令

功能	命令	说明
初始化项目	`uv init <project_name>`	创建项目结构，生成 `pyproject.toml`
添加依赖	`uv add requests`	安装包并更新锁文件
开发依赖	`uv add --dev pytest`	添加开发环境依赖
同步环境	`uv sync`	根据锁文件安装/更新所有依赖
运行脚本	`uv run python main.py`	在临时或现有虚拟环境中运行代码
管理 Python	`uv python install 3.12`	自动下载并管理特定 Python 版本
Pip 兼容模式	`uv pip install -r requirements.txt`	像 pip 一样使用（用于旧项目）
显示树	`uv tree`	查看依赖树

典型工作流

# 1. 创建新项目uv init my_projectcd my_project# 2. 添加依赖uv add flask# 3. 运行代码（自动创建/激活虚拟环境）uv run python app.py# 4. 部署/同步uv sync

`uv` 与 `pip` 的深度对比

特性	`pip`	`uv`
语言	Python	Rust
速度	较慢（尤其是解析依赖时）	极快 (10-100x)
定位	包安装器	项目 + 包 + 环境 + Python 版本管理器
虚拟环境	需配合 `venv` / `virtualenv`	内置自动管理 (`.venv`)
依赖锁定	需配合 `pip-tools` 或手动 freeze	内置锁文件 (`uv.lock`)
Python 版本	无法管理 (需 `pyenv`)	内置管理 (`uv python`)
配置文件	`requirements.txt` (非标准)	`pyproject.toml` (标准) + `uv.lock`
兼容性	官方标准	兼容 `pip` 命令和生态
成熟度	非常成熟 (十年 +)	较新 (但迭代极快，已稳定)

核心问题：

可以直接把 `pip` 换成 `uv` 吗？

简短回答：可以，且推荐在新项目中这样做，但要注意场景。

为什么推荐替换？

效率提升：在 CI/CD 流水线或本地开发中，uv 能节省大量等待时间。
简化流程：不再需要单独安装 pyenv、virtualenv、poetry，一个 uv 搞定所有。
标准回归：uv 推动使用 pyproject.toml 这一 Python 官方标准，而不是 setup.py 或单纯的 requirements.txt。

替换的两种模式

模式 A：完全项目化管理（推荐用于新项目）不再使用 pip install，而是使用 uv 的原生命令。

❌ pip install requests
✅ uv add requests
❌ python main.py
✅ uv run main.py
优点：依赖隔离好，有锁文件，可复现性强。

模式 B：Pip 兼容模式（推荐用于旧项目迁移）保留 requirements.txt 工作流，仅替换底层引擎。

命令：uv pip install -r requirements.txt
你可以设置别名：alias pip=uv (在 shell 配置中)
优点：无需修改现有项目结构，立即享受速度提升。

需要注意的风险与建议

不要卸载系统自带的 pip：

在 Linux/macOS 上，操作系统可能依赖系统 Python 的 pip。强制替换系统 pip 可能导致系统工具损坏。
建议：在用户空间使用 uv，或者在 CI/CD 和 Docker 环境中优先使用 uv。

pyproject.toml 支持：

uv 鼓励使用 pyproject.toml 管理依赖。如果你的老项目只有 requirements.txt，可以使用 uv pip 模式，或者逐步迁移到 uv init 管理的项目结构。

私有源/复杂依赖：

uv 对大多数 PyPI 包支持良好。如果你的公司使用复杂的私有源、需要特殊的 setup.py 逻辑构建包，建议先在小范围测试兼容性（虽然 uv 兼容性已经非常高）。

团队协作：

如果团队引入 uv，需要确保所有成员的 uv 版本一致（或锁文件兼容），并提交 uv.lock 文件到 Git。

总结与建议

场景	建议
全新 Python 项目	强烈推荐使用 `uv`。使用 `uv init` 和 `uv add`，体验最佳。
现有项目 (CI/CD)	推荐替换。在 Dockerfile 或 GitHub Actions 中使用 `uv pip install` 加速构建。
现有项目 (本地开发)	推荐尝试。使用 `uv sync` 替代 `pip install -r requirements.txt`。
系统环境	不要替换。保留系统 `pip`，仅在用户项目或虚拟环境中使用 `uv`。
复杂构建包	谨慎。如果包依赖复杂的 `setup.py` 脚本，先测试 `uv` 是否能正确构建。

安装包

# 安装单个包uv pip install requests# 安装多个包uv pip install requests pandas numpy# 从 requirements.txt 安装uv pip install -r requirements.txt# 安装特定版本uv pip install "django>=4.0,<5.0"

卸载包

uv pip uninstall requests

列出已安装的包

uv pip listuv pip freeze

创建虚拟环境

# 创建虚拟环境uv venv# 指定 Python 版本uv venv --python 3.11# 指定虚拟环境路径uv venv .venv

激活虚拟环境

# Linux/macOSsource .venv/bin/activate# Windows.venv\Scripts\activate

初始化新项目

# 创建新项目uv init my-projectcd my-project# 项目结构# my-project/# ├── pyproject.toml# ├── README.md# └── src/

添加依赖

# 添加依赖到项目uv add requests# 添加开发依赖uv add --dev pytest# 添加特定版本uv add "fastapi>=0.100.0"

移除依赖

uv remove requests

运行项目

# 运行 Python 脚本uv run python script.py# 运行命令uv run pytest

同步依赖

# 根据 pyproject.toml 同步依赖uv sync

Python 版本管理

# 列出可用的 Python 版本uv python list# 安装特定 Python 版本uv python install 3.11# 查看已安装的 Python 版本uv python list --only-installed

锁文件管理

# 生成锁文件uv lock# 更新锁文件uv lock --upgrade# 更新特定包uv lock --upgrade-package requests

性能对比

操作	pip	uv	提升
安装 Django	5.2s	0.3s	17x
安装 Pandas	8.1s	0.5s	16x
冷缓存安装	30s	2s	15x

🎯 常用命令速查

# 包管理uv pip install <package>      # 安装包uv pip uninstall <package>    # 卸载包uv pip list                   # 列出包uv pip freeze                 # 导出依赖# 虚拟环境uv venv                       # 创建虚拟环境uv venv --python 3.11         # 指定 Python 版本# 项目管理uv init <project>             # 初始化项目uv add <package>              # 添加依赖uv remove <package>           # 移除依赖uv sync                       # 同步依赖uv run <command>              # 运行命令uv lock                       # 生成锁文件# Python 版本uv python list                # 列出 Python 版本uv python install 3.11        # 安装 Python 版本

从 pip 迁移

# 替换命令即可pip install requests  →  uv pip install requestspip freeze           →  uv pip freeze

从 pipenv 迁移

# Pipfile → pyproject.toml# 需要手动转换配置文件

UV 与 PIP 的详细对比

特性	pip	uv	说明
速度	基准	10-100倍	uv 用 Rust 编写，性能极强
依赖解析	较慢，可能不完整	快速且完整	uv 使用现代解析算法
缓存机制	简单缓存	全局智能缓存	uv 缓存更高效
虚拟环境	需要 venv 模块	内置支持	uv 集成环境管理
锁文件	需要 pip-tools	原生支持	uv 自带锁文件功能
Python 版本管理	❌	✅	uv 可管理 Python 版本
项目管理	❌	✅	uv 类似 poetry/pipenv
兼容性	标准	完全兼容 pip	uv 兼容 pip 生态
安装依赖	Python	无需 Python	uv 是独立可执行文件

✅ 可以直接替换的命令

# 安装包pip install requests          →  uv pip install requestspip install -r requirements.txt  →  uv pip install -r requirements.txt# 卸载包pip uninstall requests        →  uv pip uninstall requests# 列出包pip list                      →  uv pip listpip freeze                    →  uv pip freezepip freeze > requirements.txt →  uv pip freeze > requirements.txt# 显示包信息pip show requests             →  uv pip show requests# 搜索包（注意：uv 暂不支持 search）pip search package            →  ❌ uv 不支持# 检查依赖pip check                     →  uv pip check# 安装可编辑模式pip install -e .              →  uv pip install -e .

简单脚本项目（可直接替换）- 可以直接替换，只需将 `pip` 改为 `uv pip`

# === 使用 pip ===python -m venv .venvsource .venv/bin/activatepip install requests pandaspython script.py# === 使用 uv（直接替换）===uv venvsource .venv/bin/activateuv pip install requests pandaspython script.py

使用 requirements.txt 的项目（可直接替换）

# === 使用 pip ===pip install -r requirements.txtpip freeze > requirements.txt# === 使用 uv（直接替换）===uv pip install -r requirements.txtuv pip freeze > requirements.txt

现代项目管理（推荐用 uv 新特性）

# === 使用 pip + pip-tools ===pip install pip-toolsecho "requests" > requirements.inpip-compile requirements.inpip-sync requirements.txt# === 使用 uv（更简单）===uv inituv add requestsuv sync

⚠️ 不能直接替换的情况

1. pip search 命令

pip search package    # uv 不支持（PyPI 已禁用此 API）

2. pip download

pip download requests --dest ./packages/# uv 暂无直接等价命令

3. pip wheel

pip wheel requests# uv 暂不支持构建 wheel

4. pip install –user

pip install --user requests# uv 不支持用户级安装（推荐使用虚拟环境）

可以直接替换的场景（90%+）

✅ pip install → uv pip install
✅ pip install -r requirements.txt → uv pip install -r requirements.txt
✅ pip uninstall → uv pip uninstall
✅ pip freeze → uv pip freeze
✅ pip list → uv pip list

需要注意的场景

⚠️ pip search – uv 不支持
⚠️ pip download – 需要其他方案
⚠️ pip wheel – uv 暂不支持
⚠️ 全局安装 – uv 推荐用虚拟环境