UV 包管理工具：替代 pip 的现代化解决方案

安装

方法一：使用安装脚本

# macOS 和 Linux
curl -LsSf https://astral.sh/uv/install.sh | sh# Windows PowerShell
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

方法二：使用包管理器

# macOS (Homebrew)
brew install uv# Windows (Scoop)
scoop install uv# 通过 pip 安装
pip install uv

入门

使用虚拟环境

1. 创建虚拟环境

# 创建一个新的虚拟环境
uv venv myproject# 创建指定 Python 版本的虚拟环境
uv venv --python 3.11 myproject# 激活虚拟环境
# Linux/macOS:
source myproject/bin/activate
# Windows:
myproject\Scripts\activate

2.安装包

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

使用uv方式

1.项目初始化

# 初始化一个新项目
uv init my_uv_test
cd my_uv_test

# 查看项目结构
tree ..
├── main.py
├── pyproject.toml
└── README.md1 directory, 3 files

使用 pyproject.toml 管理依赖

[project]
name = "my-uv-test"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = []

3. 依赖管理

安装依赖

# 安装项目依赖（从 pyproject.toml）
uv pip install -e .# 安装开发依赖
uv pip install -e ".[dev]"# 安装所有可选依赖
uv pip install -e ".[dev,docs,web]"# 生成锁定文件
uv pip freeze > requirements.lock# 同步依赖（确保环境与 requirements.txt 完全一致）
uv pip sync requirements.txt

添加依赖

# 添加生产依赖
uv add requests
uv add "django>=4.0,<5.0"
uv add requests beautifulsoup4 pandas# 添加开发依赖
uv add --dev pytest black flake8
uv add --dev "pytest>=7.0"# 添加可选依赖组
uv add --group docs sphinx sphinx-rtd-theme
uv add --group web fastapi uvicorn

添加依赖后再次查看pyproject.toml

[project]
name = "my-uv-test"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = ["requests>=2.32.3",
]

运行

uv run 选择 Python 版本的优先级顺序：

1. 明确指定版本（最高优先级）

uv run --python 3.11 script.py
uv run --python python3.12 script.py
uv run --python /usr/bin/python3.10 script.py

2. 项目配置文件

如果有 pyproject.toml：

[project]
requires-python = ">=3.9"

或者 .python-version 文件：

3.11.5

3. 环境变量

export UV_PYTHON=3.11
uv run script.py

4. 系统默认 Python

如果以上都没有，uv 会按顺序查找：

• python3
• python
• 系统 PATH 中的第一个可用 Python

建议： 在项目中明确指定 Python 版本，避免环境差异导致的问题

使用 uv 一句话运行 Python 文件

uv run script.py

在没有 pyproject.toml 的情况下，uv 有几种方式来处理依赖：

1. 使用 `--with` 参数临时安装包

uv run --with requests --with pandas script.py

2. 通过脚本内联声明依赖（PEP 723）

在 Python 脚本顶部添加特殊注释：

# /// script
# dependencies = [
#   "requests",
#   "pandas>=1.0",
# ]
# ///import requests
import pandas as pd# 你的代码...

然后直接运行：

uv run script.py

3. 使用 requirements.txt

如果目录下有 requirements.txt，uv 会自动读取：

uv run script.py

4. 完全不管理依赖

如果没有以上任何配置，uv run 会：

• 创建一个临时的虚拟环境
• 只安装 Python 标准库

• 如果脚本导入了第三方包但没有声明依赖，会报 ImportError
  推荐做法： 使用 PEP 723 的内联依赖声明，这样脚本是自包含的，任何人都能直接用 uv run script.py 运行。

uv的优缺点

这是一份很好的 uv 使用指南！我来补充一下 uv 的优缺点分析：

uv 的优缺点

优点 ⭐

1. 极快的速度

• 用 Rust 编写，比 pip 快 10-100 倍
• 并行下载和安装包
• 智能缓存机制

2. 统一的工具链

# 一个工具搞定所有事情
uv venv        # 创建虚拟环境
uv pip install # 包管理
uv run         # 运行脚本
uv add         # 添加依赖

3. 现代化的依赖管理

• 支持 pyproject.toml

• 自动生成锁定文件
• 依赖组管理（dev, docs, test 等）

4. 开箱即用

# 无需预先创建虚拟环境
uv run --with requests script.py

5. PEP 723 支持

# /// script
# dependencies = ["requests"]
# ///
import requests

6. 跨平台一致性

• Windows、macOS、Linux 行为一致
• 统一的安装方式

缺点 ⚠️

1. 生态系统兼容性

• 某些包的构建可能有问题
• 复杂的 C 扩展包支持不完善
• 企业环境的私有源配置较复杂

2. 学习成本

• 新的命令和概念
• 与传统 pip/virtualenv 工作流不同
• 团队需要统一工具

3. 相对年轻

• 社区相对较小
• 文档和教程不如 pip 丰富
• 可能存在未发现的 bug

4. 依赖 Rust 生态

• 某些平台可能缺少预编译二进制
• 从源码编译需要 Rust 工具链

适用场景

✅ 推荐使用

• 新项目开发
• 对速度有要求的 CI/CD
• 现代 Python 开发工作流
• 个人项目和学习

❌ 谨慎使用

• 传统企业环境
• 复杂的遗留项目
• 需要特殊包构建的项目
• 团队对新工具抗拒

总结

uv 是 Python 包管理的未来趋势，特别适合追求效率的现代开发者。虽然还有一些兼容性问题，但其速度和易用性优势明显，值得在新项目中尝试使用。