AI News
中文资讯 掘金 AI Wed, 19 Aug 2026 正文 ok 616 words

uv 全面指南：比 pip 快 100 倍的 Python 包管理器，从安装到团队落地

英文标题：uv 全面指南：比 pip 快 100 倍的 Python 包管理器，从安装到团队落地

uv 是 Rust 写的 Python 包管理器，比 pip 快 10~100 倍。本文覆盖安装、uv add/sync/lock 工作流、Python 版本管理、uvx、CI 与 Docker 落地、国内镜像配置与避坑，附完整命令对照表。
打开原文相关 2 · 机会 0
media3.2 KB media589 B media6.9 KB

中文

前言：你的时间正在被 pip 悄悄浪费

先做个小测试。新建一个虚拟环境，装一个 fastapi：

python -m venv .venv && .venv/Scripts/activate
pip install fastapi

在 2026 年的今天，这仍然可能要等 30 秒以上。pip 会先做一次全量依赖解析，再一个一个地下载 wheel，最后逐个安装。如果 requirements.txt 里有几十个包，或者你每天要在多个项目间切换、反复重建环境，浪费的时间就非常可观了。

uv 就是冲着这个问题来的。它是 Astral 公司（对，就是做 Ruff 的那家）用 Rust 写的 Python 包管理器和解析器，号称比 pip 快 10~100 倍 。本文不吹概念，直接给你一套从「看懂它」到「在团队里落地」的完整路径，所有命令都经过验证。

一、uv 为什么能快这么多

快不是玄学，主要来自四个设计：

  1. Rust 实现 ：下载、解压、安装全链路没有 Python 解释器参与，省掉了大量 Python 层开销；
  2. 全局内容寻址缓存 ：所有下载过的 wheel 存在一个全局缓存里（Linux/macOS 在 ~/.cache/uv，Windows 在 %LOCALAPPDATA%\uv\cache），新项目安装时通过硬链接直接复用 ，而不是重新复制；
  3. 并发下载 ：同时拉取所有依赖，而不是像 pip 那样逐个排队；
  4. 更聪明的解析器 ：基于 PubGrub 算法（Cargo 同款），一次解析出完整依赖图，锁定精确版本。

同样的依赖，pip 需要 30 秒，uv 通常 1~2 秒内完成——第一次要下包，之后几乎是瞬间。

二、安装 uv（三条路任选）

pip install uv


curl -LsSf https://astral.sh/uv/install.sh | sh


powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

包管理器用户：winget install astral-sh.uv、scoop install uv、brew install uv 也都支持。

装完验证：

uv --version

三、先忘掉复杂概念：最常用的三个命令

uv 的定位是「全家桶」，但日常 90% 的场景只需要三个命令：

1. uv venv —— 创建虚拟环境

cd myproject
uv venv

如果本机没有合适的 Python 版本，uv 会自动下载一个（见第五节），完全不需要手动装。

2. uv pip install —— 兼容 pip 的安装命令

uv pip install -r requirements.txt
uv pip install fastapi "pydantic>=2.0" pytest --dev

它兼容 pip 的参数习惯，旧项目可以直接切换。

3. uv run —— 一键执行

uv run python main.py

uv run main.py

uv run 会自动激活当前目录的 .venv 并运行命令，不需要手动 source activate。

四、从 requirements.txt 迁移到 uv.lock

临时项目用 uv pip install 就够了；长期维护的项目建议直接上pyproject.toml + uv.lock，这才是 uv 的真正威力。

4.1 初始化项目

uv init myapp
cd myapp

这会生成：

myapp/
├── .python-version    
├── pyproject.toml     
├── main.py
└── README.md

4.2 添加依赖

uv add fastapi "uvicorn[standard]" httpx

uv add 会做两件事：把依赖写进 pyproject.toml 的 [project.dependencies]，同时生成/更新 uv.lock 锁定精确版本。

4.3 同步安装（对应 pip 的 install）

uv sync

uv sync 严格按照 uv.lock 安装，保证团队每个人、每台 CI 机器拿到的依赖字节级一致 。新增成员克隆仓库后只需要两步：

uv sync
uv run python main.py

4.4 升级依赖

uv lock --upgrade        
uv lock --upgrade-package fastapi

4.5 已有 requirements.txt 怎么办？

uv add -r requirements.txt

之后删掉 requirements.txt，统一走 pyproject.toml。

五、Python 版本管理（替代 pyenv）

uv 内置了 Python 版本管理，再也不用装 pyenv：

uv python install 3.12
uv python install 3.11.9


uv python list


uv python pin 3.12

项目目录下有了 .python-version 后，uv venv、uv run 都会自动使用对应版本。在 2026 年，新机器配 Python 环境只需要一个 uv。

六、uvx：跑一次性工具

uvx（uv 的孪生命令）用于执行临时工具，装完即用、用完即走，不污染环境：

uvx ruff check .


uvx serve .


uvx yamllint config.yml

原理：工具被缓存到全局，重复运行秒开。CI 里特别适合——不用预先 pip install 工具链。

七、在 CI / Docker 里落地

GitHub Actions

steps:
  - uses: actions/checkout@v4
  - uses: astral-sh/setup-uv@v5
    with:
      enable-cache: true        
  - run: uv sync --frozen       
  - run: uv run pytest

Dockerfile

FROM python:3.12-slim

# 安装 uv（官方镜像推荐方式）
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

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

COPY . .
CMD ["uv", "run", "uvicorn", "app.main:app", "--host", "0.0.0.0"]

关键点：先拷贝 pyproject.toml 和 uv.lock 再 uv sync，可以充分利用 Docker 层缓存——依赖没变时这一层不会重建。

八、国内网络与私有源配置

uv 支持环境变量和配置文件（pyproject.toml 或 uv.toml）：

uv pip install -i https://pypi.tuna.tsinghua.edu.cn/simple


export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

私有仓库（如公司 Nexus / Artifactory）：

[[index]]
url = "https://pypi.org/simple"

[[index]]
url = "https://nexus.example.com/repository/pypi/simple"
priority = "primary"

九、三个容易踩的坑

坑 1：把 uv pip install 和 uv add 混着用

一个项目里如果两种方式都用了，pyproject.toml 和实际环境可能不一致。新项目只用uv add / uv sync；临时环境才用 uv pip install。

坑 2：在 CI 里忘加 --frozen

不加 --frozen 时，uv sync 在 lock 文件过期时会自动重新解析 ，导致 CI 装的版本和本地不一致。生产流程一律加 --frozen，让「锁文件过期」直接变成构建错误，倒逼开发者及时更新。

坑 3：以为 uv 会自己找 Python

uv venv 在系统没有合适 Python 时会自动下载，但如果系统里恰好有一个旧版本 （比如 3.9），它会「尊重」旧版本而不是自动升级。项目里用 uv python pin 3.12 显式固定，避免同事的机器环境不一致。

十、命令对照速查表

场景 pip 时代 uv 时代
创建环境 python -m venv .venv uv venv
安装依赖 pip install -r requirements.txt uv sync（有 lock）/ uv pip install -r requirements.txt
添加依赖 pip install fastapi && pip freeze > requirements.txt uv add fastapi
移除依赖 手动改 requirements.txt uv remove fastapi
运行脚本 source .venv/bin/activate && python main.py uv run python main.py
管理 Python 版本 装 pyenv uv python install / pin
一次性工具 pip install ruff && ruff check . uvx ruff check .

结语

uv 最聪明的地方在于学习成本趋近于零 ：uv pip install 完全兼容 pip 的肌肉记忆，而 uv add / uv sync / uv.lock 又提供了现代包管理器该有的可复现性。它没有发明新概念，只是把「依赖解析 + 下载 + 安装 + 版本管理」这些苦活全部重做了一遍。

建议迁移节奏：第一周 ，把个人项目的 pip install 换成 uv pip install（零成本）；第一个月 ，新项目直接用 uv init，走 uv add / uv sync 流程；一个季度内 ，把团队 CI 和 Dockerfile 切到 uv，你会看到构建时间肉眼可见地缩短。

如果你的团队还在争论「用 pip 还是 poetry」——别争了，试试 uv，答案会自己浮现。

English / 原文

前言：你的时间正在被 pip 悄悄浪费

先做个小测试。新建一个虚拟环境，装一个 fastapi：

python -m venv .venv && .venv/Scripts/activate
pip install fastapi

在 2026 年的今天，这仍然可能要等 30 秒以上。pip 会先做一次全量依赖解析，再一个一个地下载 wheel，最后逐个安装。如果 requirements.txt 里有几十个包，或者你每天要在多个项目间切换、反复重建环境，浪费的时间就非常可观了。

uv 就是冲着这个问题来的。它是 Astral 公司（对，就是做 Ruff 的那家）用 Rust 写的 Python 包管理器和解析器，号称比 pip 快 10~100 倍 。本文不吹概念，直接给你一套从「看懂它」到「在团队里落地」的完整路径，所有命令都经过验证。

一、uv 为什么能快这么多

快不是玄学，主要来自四个设计：

  1. Rust 实现 ：下载、解压、安装全链路没有 Python 解释器参与，省掉了大量 Python 层开销；
  2. 全局内容寻址缓存 ：所有下载过的 wheel 存在一个全局缓存里（Linux/macOS 在 ~/.cache/uv，Windows 在 %LOCALAPPDATA%\uv\cache），新项目安装时通过硬链接直接复用 ，而不是重新复制；
  3. 并发下载 ：同时拉取所有依赖，而不是像 pip 那样逐个排队；
  4. 更聪明的解析器 ：基于 PubGrub 算法（Cargo 同款），一次解析出完整依赖图，锁定精确版本。

同样的依赖，pip 需要 30 秒，uv 通常 1~2 秒内完成——第一次要下包，之后几乎是瞬间。

二、安装 uv（三条路任选）

pip install uv


curl -LsSf https://astral.sh/uv/install.sh | sh


powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

包管理器用户：winget install astral-sh.uv、scoop install uv、brew install uv 也都支持。

装完验证：

uv --version

三、先忘掉复杂概念：最常用的三个命令

uv 的定位是「全家桶」，但日常 90% 的场景只需要三个命令：

1. uv venv —— 创建虚拟环境

cd myproject
uv venv

如果本机没有合适的 Python 版本，uv 会自动下载一个（见第五节），完全不需要手动装。

2. uv pip install —— 兼容 pip 的安装命令

uv pip install -r requirements.txt
uv pip install fastapi "pydantic>=2.0" pytest --dev

它兼容 pip 的参数习惯，旧项目可以直接切换。

3. uv run —— 一键执行

uv run python main.py

uv run main.py

uv run 会自动激活当前目录的 .venv 并运行命令，不需要手动 source activate。

四、从 requirements.txt 迁移到 uv.lock

临时项目用 uv pip install 就够了；长期维护的项目建议直接上pyproject.toml + uv.lock，这才是 uv 的真正威力。

4.1 初始化项目

uv init myapp
cd myapp

这会生成：

myapp/
├── .python-version    
├── pyproject.toml     
├── main.py
└── README.md

4.2 添加依赖

uv add fastapi "uvicorn[standard]" httpx

uv add 会做两件事：把依赖写进 pyproject.toml 的 [project.dependencies]，同时生成/更新 uv.lock 锁定精确版本。

4.3 同步安装（对应 pip 的 install）

uv sync

uv sync 严格按照 uv.lock 安装，保证团队每个人、每台 CI 机器拿到的依赖字节级一致 。新增成员克隆仓库后只需要两步：

uv sync
uv run python main.py

4.4 升级依赖

uv lock --upgrade        
uv lock --upgrade-package fastapi

4.5 已有 requirements.txt 怎么办？

uv add -r requirements.txt

之后删掉 requirements.txt，统一走 pyproject.toml。

五、Python 版本管理（替代 pyenv）

uv 内置了 Python 版本管理，再也不用装 pyenv：

uv python install 3.12
uv python install 3.11.9


uv python list


uv python pin 3.12

项目目录下有了 .python-version 后，uv venv、uv run 都会自动使用对应版本。在 2026 年，新机器配 Python 环境只需要一个 uv。

六、uvx：跑一次性工具

uvx（uv 的孪生命令）用于执行临时工具，装完即用、用完即走，不污染环境：

uvx ruff check .


uvx serve .


uvx yamllint config.yml

原理：工具被缓存到全局，重复运行秒开。CI 里特别适合——不用预先 pip install 工具链。

七、在 CI / Docker 里落地

GitHub Actions

steps:
  - uses: actions/checkout@v4
  - uses: astral-sh/setup-uv@v5
    with:
      enable-cache: true        
  - run: uv sync --frozen       
  - run: uv run pytest

Dockerfile

FROM python:3.12-slim

# 安装 uv（官方镜像推荐方式）
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv

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

COPY . .
CMD ["uv", "run", "uvicorn", "app.main:app", "--host", "0.0.0.0"]

关键点：先拷贝 pyproject.toml 和 uv.lock 再 uv sync，可以充分利用 Docker 层缓存——依赖没变时这一层不会重建。

八、国内网络与私有源配置

uv 支持环境变量和配置文件（pyproject.toml 或 uv.toml）：

uv pip install -i https://pypi.tuna.tsinghua.edu.cn/simple


export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple

私有仓库（如公司 Nexus / Artifactory）：

[[index]]
url = "https://pypi.org/simple"

[[index]]
url = "https://nexus.example.com/repository/pypi/simple"
priority = "primary"

九、三个容易踩的坑

坑 1：把 uv pip install 和 uv add 混着用

一个项目里如果两种方式都用了，pyproject.toml 和实际环境可能不一致。新项目只用uv add / uv sync；临时环境才用 uv pip install。

坑 2：在 CI 里忘加 --frozen

不加 --frozen 时，uv sync 在 lock 文件过期时会自动重新解析 ，导致 CI 装的版本和本地不一致。生产流程一律加 --frozen，让「锁文件过期」直接变成构建错误，倒逼开发者及时更新。

坑 3：以为 uv 会自己找 Python

uv venv 在系统没有合适 Python 时会自动下载，但如果系统里恰好有一个旧版本 （比如 3.9），它会「尊重」旧版本而不是自动升级。项目里用 uv python pin 3.12 显式固定，避免同事的机器环境不一致。

十、命令对照速查表

场景 pip 时代 uv 时代
创建环境 python -m venv .venv uv venv
安装依赖 pip install -r requirements.txt uv sync（有 lock）/ uv pip install -r requirements.txt
添加依赖 pip install fastapi && pip freeze > requirements.txt uv add fastapi
移除依赖 手动改 requirements.txt uv remove fastapi
运行脚本 source .venv/bin/activate && python main.py uv run python main.py
管理 Python 版本 装 pyenv uv python install / pin
一次性工具 pip install ruff && ruff check . uvx ruff check .

结语

uv 最聪明的地方在于学习成本趋近于零 ：uv pip install 完全兼容 pip 的肌肉记忆，而 uv add / uv sync / uv.lock 又提供了现代包管理器该有的可复现性。它没有发明新概念，只是把「依赖解析 + 下载 + 安装 + 版本管理」这些苦活全部重做了一遍。

建议迁移节奏：第一周 ，把个人项目的 pip install 换成 uv pip install（零成本）；第一个月 ，新项目直接用 uv init，走 uv add / uv sync 流程；一个季度内 ，把团队 CI 和 Dockerfile 切到 uv，你会看到构建时间肉眼可见地缩短。

如果你的团队还在争论「用 pip 还是 poetry」——别争了，试试 uv，答案会自己浮现。