uv、poetry、 pip 全面对比 & uv 实操手册

lyjin 2025-07-22

> 一次搞清楚三套工具的定位、优缺点、典型工作流，并附上 **`uv` 详细操作命令**。

---

## 1. 一句话定位

- **uv**：Rust 实现的“全家桶”——包管理 + 虚拟环境 + 解析锁定 + 运行命令 + Python 版本管理，全都要，还巨快。
- **poetry**：偏“项目管理器”，围绕 `pyproject.toml` 做依赖解析、打包发布，体验统一但解析速度偶尔拉胯。
- **pip (+ venv + pip-tools)**：原生拼装流派，灵活但碎片化；要想可重复构建得靠一堆脚本和 `pip-tools`。

---

## 2. 功能矩阵（速查表）

| 特性 / 功能                         | **uv**                                              | **poetry**                                            | **pip (+ venv + pip-tools)**                                  |
|-------------------------------------|-----------------------------------------------------|-------------------------------------------------------|----------------------------------------------------------------|
| 依赖解析 & 锁定                     | ✅ `uv lock`，生成 `uv.lock`，速度极快               | ✅ 内建解析器，生成 `poetry.lock`                      | ❌ `pip` 无锁；需 `pip-tools` 的 `pip-compile` 才能锁定        |
| 虚拟环境管理                       | ✅ 自动或 `uv venv`                                  | ✅ 自动或 `poetry env use`                             | ⚠️ 手动 `python -m venv`                                       |
| Python 版本安装/管理               | ✅ `uv python install 3.12`                          | ⚠️ 只能声明版本，安装靠你自己（pyenv/系统）            | ❌ 同左                                                         |
| 安装 & 解析速度                    | 🚀 Rust 并行解析、缓存好，极快                       | 🐢 较慢，尤其遇到复杂依赖冲突时                       | 🐌 串行解析，速度看缘分                                         |
| 单行添加依赖                       | `uv add requests`                                   | `poetry add requests`                                  | `pip install requests`                                         |
| 开发依赖（dev deps）               | `uv add -D pytest`                                   | `poetry add -D pytest`                                 | `pip install -r dev-requirements.txt`                          |
| 自动激活 env 运行命令              | `uv run pytest`                                     | `poetry run pytest`                                    | `source .venv/bin/activate && pytest`                          |
| 导出 requirements.txt              | `uv export --format requirements.txt`               | `poetry export -f requirements.txt`                    | 原生使用它                                                     |
| Monorepo / Workspace 支持          | 🌱 初步支持，仍在演进                                 | ⚠️ 有 workspaces，但体验一般                            | 手搓脚本                                                       |
| 可移植性 / 与 pip 生态兼容         | ✅ 可导出/可使用现成 pyproject                        | ✅ 同左                                                 | ✅ pip 就是生态基准                                             |
| 学习成本 / 迁移成本                | 低（语义直白、命令统一）                             | 中（需要理解它的一套 workflow）                         | 低（你可能已经会），但组装其它工具时成本升高                  |

---

## 3. 三者典型工作流对照

### 3.1 初始化项目

```bash
# uv
uv init myproj
cd myproj

# poetry
poetry new myproj
cd myproj

# pip + venv
mkdir myproj && cd myproj
python -m venv .venv
source .venv/bin/activate  # Windows 用 .venv\Scripts\activate
```

### 3.2 安装依赖 / 锁定

```bash
# uv
uv add fastapi uvicorn
uv sync                # 同步依赖到虚拟环境（别人拉仓库后也用这个）

# poetry
poetry add fastapi uvicorn
poetry install         # 别人拉仓库后

# pip + pip-tools
pip install pip-tools
echo "fastapi\nuvicorn" > requirements.in
pip-compile requirements.in   # 生成 requirements.txt
pip-sync requirements.txt     # 安装锁定版本
```

### 3.3 运行命令

```bash
# uv
uv run pytest

# poetry
poetry run pytest

# pip
pytest    # 先手动激活环境
```

### 3.4 Python 版本管理

```bash
# uv
uv python install 3.12
uv python list
uv python pin 3.12   # 固定项目 Python 版本（写入 pyproject）

# poetry
# 无安装管理命令，只能写 pyproject 的 python = "^3.12"

# pip
# 自己装，用 pyenv/conda/系统包管理器
```

---

## 4. 何时用谁？建议

- **你想：快、简单、统一命令、还能管 Python 版本 → 用 `uv`。**
- 团队深度绑定 poetry（发布流程、插件体系）？那就继续用 poetry，没必要为换而换。
- 老项目纯 pip/requirements.txt，也能继续用，只要别忘记锁版本（pip-tools）。

### 混合场景兼容
- `uv` 可以 **读现有 pyproject**，生成自己的锁文件。
- 需要兼容纯 pip 的部署？`uv export --format requirements.txt > requirements.txt`。

---

## 5. uv 实操命令详解

> **提示**：几乎所有命令都能加 `-h` 看帮助；大部分操作会自动创建/使用 `.venv`。

### 5.1 安装 & 升级 uv

```bash
# Linux / macOS
curl -Ls https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

# 升级
uv self update
```

### 5.2 项目初始化

```bash
# 在当前目录创建 pyproject.toml / uv.lock / .venv
uv init

# 指定项目名（会创建文件夹）
uv init myproj
```

可选项：  
- `--python 3.12`：初始化时就指定 Python 版本（会自动安装/使用）。  
- `--no-venv`：不自动创建虚拟环境。

### 5.3 依赖管理

```bash
# 添加运行时依赖
uv add requests httpx

# 添加开发依赖（只在 dev 分组）
uv add -D pytest pytest-asyncio

# 移除依赖
uv remove httpx

# 手动解析/刷新锁文件（一般不用，add/sync 已包含）
uv lock

# 同步依赖到虚拟环境（CI 或他人拉仓后用）
uv sync
  # --frozen 锁死版本，不允许解析变化（CI 常用）
  # --no-dev 不安装 dev 依赖（生产环境常用）
```

**从 requirements.txt 迁移：**  
```bash
uv add -r requirements.txt
```

**导出为 requirements.txt：**  
```bash
uv export --format requirements.txt > requirements.txt
uv export --format pip-tools      > requirements.in   # 还可导出成 pip-tools 的输入
```

### 5.4 运行命令（自动在虚拟环境里执行）

```bash
uv run python script.py
uv run pytest -k "not slow"
uv run uvicorn app:app --reload
```

> 不再需要 `source .venv/bin/activate`，也不用 `poetry run` 那样不断重复。

### 5.5 虚拟环境管理

```bash
# 明确创建虚拟环境（默认项目根目录 .venv）
uv venv

# 列出所有 uv 管理的 venv
uv venv list

# 删除
uv venv remove .venv
```

可在全局配置中设置虚拟环境位置（如统一放 cache），参考官方文档。

### 5.6 Python 版本管理

```bash
# 安装
uv python install 3.12.4
uv python install pypy3.10

# 查看本地已安装版本
uv python list

# 在当前项目 pin 固定版本（写 pyproject）
uv python pin 3.12

# 切换当前项目使用的解释器
uv python use 3.11

# 卸载（慎用）
uv python uninstall 3.10.13
```

### 5.7 发布/打包（简单说明）

`uv` 支持构建 wheel/sdist：

```bash
uv build
uv publish
```

目前生态还在补齐，复杂场景（多模块、插件、build-backend 自定义）需要看官方文档。

### 5.8 配置文件 & 全局设置

- 读取和写入 `pyproject.toml`。
- `uv config` 查看/设置全局配置，如缓存目录、索引源、默认 python 等：

```bash
uv config get
uv config set install.with-shared-venv true
```

---

## 6. 迁移案例：从 Poetry 到 uv

假设你已有 `pyproject.toml`（Poetry 生成）：

```bash
# 1. 在项目根目录执行
uv lock      # 读 pyproject，生成 uv.lock
uv sync      # 安装依赖到虚拟环境

# 2. 之后用 uv add/remove/ sync 等即可
uv run pytest
```

Poetry 的 `[tool.poetry.scripts]` 等配置，uv 是照着 `pyproject` 规范来读的，基础部分兼容性良好。

---

## 7. CI / Docker 示例（超简版）

**GitHub Actions**:
```yaml
- name: Install uv
  run: curl -Ls https://astral.sh/uv/install.sh | sh

- name: Sync deps
  run: uv sync --frozen --no-dev

- name: Run tests
  run: uv run pytest
```

**Dockerfile**（多阶段构建示例）：
```dockerfile
FROM python:3.12-slim AS builder

# 安装 uv
RUN curl -Ls https://astral.sh/uv/install.sh | sh &&     mv ~/.local/bin/uv /usr/local/bin/uv

WORKDIR /app
COPY pyproject.toml uv.lock ./
RUN uv sync --no-dev --frozen --system

COPY . .
RUN uv run pytest  # 可选：构建时测试

FROM python:3.12-slim
WORKDIR /app

# 复制已安装的 site-packages
COPY --from=builder /usr/local/lib/python3.12 /usr/local/lib/python3.12
COPY --from=builder /app /app

CMD ["python", "main.py"]
```

---

## 8. 小坑 & 注意事项

- 默认 `.venv` 放在项目里；也可以配置使用共享缓存 env。
- `uv.lock` 是它自己的格式；不要手改（跟 poetry.lock 一样）。
- 生态新，少量高级功能还在路上（比如复杂 workspace），上之前看下文档。
- 一些公司内网不通公网 PyPI，需要配置私有源：`uv config set index-url https://your-pypi/simple`。

---

## 9. 总结

- **想省事省心、快到飞起：`uv`。**
- **对 Poetry 已经深度依赖：继续用，也没毛病。**
- **最自由/最底层：`pip + venv + pip-tools`，但脚本/规范要你自己搞。**

---

有具体场景要落地？比如：  
- 把你现有的 `pyproject.toml` / `requirements.txt` 发给我，我帮你写迁移步骤。  
- CI、Docker、私有源、镜像加速、内网部署？我都能配。

> **一句话：工具只是手段，选顺手的那个就行。**

没有评论

请登陆后评论