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

安装

方法一：使用安装脚本

# macOS 和 Linuxcurl -LsSf https://astral.sh/uv/install.sh | sh # Windows PowerShellpowershell -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_testcd my_uv_test

# 查看项目结构tree . .├── main.py├── pyproject.toml└── README.md 1 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 requestsuv add "django>=4.0,=7.0" # 添加可选依赖组uv add --group docs sphinx sphinx-rtd-themeuv 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.pyuv run --python python3.12 script.pyuv 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.11uv 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 requestsimport 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 包管理的未来趋势，特别适合追求效率的现代开发者。虽然还有一些兼容性问题，但其速度和易用性优势明显，值得在新项目中尝试使用。