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

lyj

发布 2025-07-22

140

分享

> 一次搞清楚三套工具的定位、优缺点、典型工作流，并附上 **`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、私有源、镜像加速、内网部署？我都能配。 > **一句话：工具只是手段，选顺手的那个就行。**