第二大脑 / Knowledge Bank

uv

7分钟阅读

uv

1. 定义

uv 是 Astral 公司用 Rust 写的 Python 包管理器 + 项目管理工具，定位是 pip / pip-tools / virtualenv / pipx / poetry 的统一替代品。 最大卖点：快（比 pip 快 10~100 倍），并把 Python 环境、依赖、版本管理整合到一个命令里。

类比：uv 之于 Python，相当于 pnpm 之于 Node、cargo 之于 Rust——一个工具搞定”装包 + 环境 + 项目”。

2. uv 解决了什么问题

传统 Python 工具链是割裂的：

任务传统工具uv
装包pip installuv pip install 或 uv add
虚拟环境python -m venv / virtualenvuv venv
锁定依赖pip-tools (pip-compile)uv lock
运行脚本/工具pipx runuv run / uvx
项目管理poetry / hatchuv init / uv add / uv sync
管理 Python 版本pyenvuv python install

痛点：装一套环境要在 5 个工具之间切换，每个还慢。uv 把这些全合并了，且用 Rust 实现，速度碾压。

3. 核心概念

  • uv 命令本身：跨项目的 CLI 工具，类似 pip
  • 项目模式 (Project mode)：基于 pyproject.toml + uv.lock 管理一个 Python 项目，类似 poetry
  • uv.lock：跨平台锁文件，记录所有依赖的精确版本和 hash
  • uvx / uv tool：临时运行或全局安装 CLI 工具（替代 pipx）
  • Python 版本管理：uv 自带 Python 发行版下载，不需要再装 pyenv

4. 常用命令

环境管理

uv venv                       # 在当前目录创建 .venv（默认用系统 Python）
uv venv --python 3.12         # 指定 Python 版本创建
uv python list                # 列出可用 Python 版本
uv python install 3.12        # 下载安装 Python 3.12（不需要 pyenv）

包管理（pip 兼容模式）

uv pip install requests       # 装包到当前环境
uv pip install -r requirements.txt
uv pip list                   # 列出已装包
uv pip uninstall requests
uv pip freeze                 # 导出已装包

项目管理（推荐方式）

uv init my-project            # 创建新项目（生成 pyproject.toml）
cd my-project
uv add requests               # 添加依赖，自动写入 pyproject.toml + 更新 lock
uv add --dev pytest           # 添加开发依赖
uv remove requests            # 移除依赖
uv sync                       # 按 uv.lock 同步安装环境（新人 clone 后第一步）
uv lock                       # 重新解析依赖、更新 lock 文件
uv run python main.py         # 在项目环境里运行（无需手动 activate）
uv run pytest                 # 在项目环境里跑命令

工具运行（替代 pipx）

uvx ruff check .              # 临时运行 ruff，不污染环境
uvx black main.py             # 临时运行 black
uv tool install ruff          # 全局安装 CLI 工具
uv tool list                  # 列出已装工具
uv tool upgrade ruff          # 升级工具
uv tool uninstall ruff        # 卸载工具

4.5 uv add vs uv pip install（高频困惑）

两个都能”装包”，但属于两套不同的工作模式，混用会出问题：

uv add <包>uv pip install <包>
属于项目模式（管理一个项目）pip 兼容模式（当快版 pip 用）
会改 pyproject.toml 吗✅ 写入 dependencies❌ 不写，装完不留记录
会更新 uv.lock 吗✅ 更新锁文件❌ 不碰锁文件
装到哪项目的 .venv（uv 自动管理）当前激活/指定的环境
可复现吗✅ 别人 uv sync 能还原❌ 环境是临时的、不可追踪
类比像 npm install <包>（记进 package.json）像直接 pip install（只装不记）

怎么选：

  • 在做一个项目（有 pyproject.toml）→ 一律用 uv add / uv remove，让依赖被 pyproject.toml + uv.lock 记录、可复现
  • 只是想临时装个包试试、或在非 uv 项目里当快版 pip 用 → 用 uv pip install

⚠️ 核心坑：在项目模式里用了 uv pip install，包虽然装进了 .venv，但没写进 pyproject.toml——别人 clone 后 uv sync 装不到它，“在我机器上能跑”重现。项目里要装依赖，认准 uv add。

# 项目模式（推荐）——依赖被记录、可复现
uv add requests              # 加依赖，写入 pyproject.toml + 更新 lock
uv add --dev pytest          # 开发依赖
uv remove requests           # 移除（同时清理 pyproject.toml + lock）
uv sync                      # 按 lock 还原整个环境
 
# pip 兼容模式——只装不记，临时用
uv pip install requests      # 等价于 pip install，但更快；不碰 pyproject.toml

5. uv vs pip vs poetry 速查

维度pippoetryuv
速度慢慢极快（Rust + 全局缓存）
锁文件无（freeze 不算）poetry.lockuv.lock
虚拟环境需配合 venv自动自动
Python 版本管理不能不能能
项目管理不能能能
pip 兼容—部分兼容子命令兼容
全局缓存无无有（硬链接，省磁盘）

6. 典型工作流

新项目

uv init my-app
cd my-app
uv add fastapi uvicorn
uv add --dev pytest ruff
uv run uvicorn main:app --reload

接手已有项目

git clone <repo>
cd <repo>
uv sync                 # 一条命令搞定：读 pyproject.toml + uv.lock，建 .venv，装所有依赖

临时跑个工具（不污染系统）

uvx httpie              # 临时跑 http 命令行工具

7. 常见坑

  • uv sync 和 uv pip install 混用：项目模式下用 uv sync，不要再用 uv pip install 手动装包，否则 lock 会乱
  • uv run 必须在项目目录：它会向上找 pyproject.toml，找不到就用系统环境
  • 速度突然变慢：第一次跑会下载 Python 和构建缓存，之后才会快；持续慢可能是缓存目录权限问题
  • uv add 后包没生效：检查是不是在正确的 .venv 里运行；项目模式下 uv 自动管理 venv，不用手动 activate

8. 延伸阅读 / 关联概念

  • pyproject.toml — 现代 Python 项目配置标准，uv / poetry / hatch 都用它
  • ruff — 同为 Astral 出品的 Python linter，也是 Rust 写的，速度极快
  • pip-tools — uv 锁文件功能的前身，pip-compile + pip-sync
  • Astral 官方文档：https://docs.astral.sh/uv/

关系图谱