UV 全面实战指南 (Python 下一代构建工具)

安装 (Installation)

pip安装方式

1

pip install uv

脚本安装

官方推荐使用独立脚本安装。这样可以确保 uv 自身不依赖于特定的 Python 环境，且更新方便。
但对于仅希望uv作为类似npm类包管理工具的话，个人觉得还是依赖python安装用一点。

macOS / Linux:

1

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

Windows (PowerShell):

1

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

安装后验证:

1
2

uv --version
# 输出示例: uv 0.5.x ...

升级 uv

1

uv self update

核心工作流：项目管理 (Project Management)

这是 uv 推荐的现代用法。它不再仅仅是 pip 的替代品，而是像 Rust 的 Cargo 或 Node 的 npm 一样管理整个项目生命周期。

初始化项目

1
2
3
4
5
6

# 创建一个新的文件夹并初始化
uv init my-project
cd my-project

# 或者在当前目录初始化
uv init

这会生成 pyproject.toml (标准配置文件) 和 .python-version。

管理依赖 (替代 pip install / poetry add)

添加依赖：

1
2
3
4
5
6
7
8

# 添加 requests
uv add requests

# 添加开发依赖 (例如 pytest)
uv add --dev pytest

# 添加特定版本
uv add "pandas<2.0"

执行这些命令会自动：1. 创建虚拟环境 2. 更新 pyproject.toml 3. 更新 uv.lock 4. 安装包。

移除依赖：

1

uv remove requests

运行代码 (替代 python / activating venv)

你不需要手动激活虚拟环境。使用 uv run，uv 会自动在项目的虚拟环境中执行命令。

1
2
3
4
5
6
7
8
9

# 运行脚本
uv run main.py

# 运行模块
uv run -m pytest

# 在虚拟环境中打开 shell
uv run bash  # (Linux/Mac)
uv run powershell # (Windows)

同步环境 (Sync)

当你拉取别人的代码后，只需运行 sync 即可让本地环境与 uv.lock 保持一致：

1

uv sync

Python 版本管理 (类似 pyenv 的功能)

uv 内置了 Python 版本管理功能，你不再需要安装 pyenv 或手动下载 Python 安装包。

1
2
3
4
5
6
7
8

# 查看可用的 Python 版本
uv python list

# 安装特定版本的 Python
uv python install 3.12

# 指定当前项目使用的 Python 版本
uv python pin 3.11

当你执行 uv run 时，如果所需版本的 Python 不存在，uv 甚至会自动为你下载并安装它。

补充：pyenv和uv的区别

直接使用区别：使用uv安装的python无法直接使用python关键字来调用或执行指令/脚本

• Pyenv 的做法（全局劫持）： pyenv 会修改你的系统环境变量（PATH），插入一个 "Shims"（垫片）。当你输入 python 时，系统实际上先拦截到 pyenv，然后 pyenv 根据你设定的 pyenv global 或 .python-version 决定调用哪个版本。
  • 结果： 终端直接输 python = pyenv 管理的 Python。
• uv 的做法（显式调用）： uv 安装的 Python 版本被存储在 uv 的内部目录中（通常是 ~/.local/share/uv/python/），它不会自动将这些目录添加到你的全局 PATH 中去覆盖系统 Python。这是为了保持系统清洁，避免“环境污染”。
  • 结果： 终端直接输 python = 操作系统自带的 Python（或者你以前装的其他 Python）。

全局工具管理 (替代 pipx)

如果你想运行黑盒子 CLI 工具（如 ruff, httpie, black），使用 uv tool 接口。

运行临时工具 (uvx)

uvx 是 uv tool run 的别名。

1
2
3
4
5

# 不安装，直接下载并运行 cowsay
uvx cowsay "Hello uv!"

# 运行 ruff 格式化代码
uvx ruff format .

安装全局工具

1
2
3
4
5

# 安装 black 到全局
uv tool install black

# 运行已安装的 black
black .

迁移指南 (Migration Guide)

这是最关键的部分，如何从旧工具迁移到 uv。

场景 A: 从 Pip / Requirements.txt 迁移

如果你有一个 requirements.txt 文件：

方式 1：单纯作为安装器使用 (Pipe interface) 如果你不想改变项目结构，只想加速安装：

1
2
3
4
5

# 创建虚拟环境 (可选，uv pip 也可以自动检测)
uv venv

# 极速安装
uv pip install -r requirements.txt

方式 2：转换为 uv 项目 (推荐) 将旧项目升级为现代管理方式：

1. 初始化 uv：uv init
2. 批量导入依赖：

1
2

cat requirements.txt | xargs uv add
# 或者手动 uv add -r requirements.txt (视版本支持情况)

场景 B: 从 Poetry 迁移

Poetry 使用 [tool.poetry] 格式，而 uv 遵循 PEP 621 标准 ([project] 格式)。

步骤：

1. 备份： 备份你的 pyproject.toml。
2. 转换配置： uv 目前不直接提供“一键转换配置格式”的命令，你需要调整 pyproject.toml 的格式。
   • 将 [tool.poetry.dependencies] 下的内容移动到 [project.dependencies]。
   • 将 [tool.poetry.group.dev.dependencies] 移动到 [dependency-groups] dev = [...] (uv 的新标准) 或 [project.optional-dependencies]。
3. 生成 Lock 文件： 删除 poetry.lock，运行：

1

uv sync

这会根据新的 pyproject.toml 生成 uv.lock。

差异对比表：

高级技巧与参数

导出依赖

如果你需要生成 requirements.txt 给不支持 uv 的环境使用：

1
2
3
4
5

# 从 pyproject.toml / uv.lock 导出
uv export --format requirements-txt > requirements.txt

# 仅导出生产环境依赖 (不含 dev)
uv export --no-dev --format requirements-txt > requirements.txt

清理缓存

虽然 uv 缓存管理很好，但有时为了释放空间：

1

uv cache clean

覆盖 pip (仅限 CI/CD 或 Docker)

在 Dockerfile 中，你可能希望直接使用 uv 安装到系统 Python (虽然 uv 默认倾向于虚拟环境)。

1
2
3
4
5

# 示例 Dockerfile 片段
COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv

# 使用系统环境安装依赖
RUN uv pip install --system -r requirements.txt

总结：应该如何使用 uv？

1. 日常开发：使用 uv init, uv add, uv run。忘记 source .venv/bin/activate。
2. 脚本任务：使用 uv run script.py，你甚至可以在脚本头部声明依赖，uv 会自动处理（Inline script metadata）。
3. CI/CD：使用 uv sync 或 uv pip install --system 来获得极速构建体验。