Python 包管理器 - uv 教程

1. 安装 `uv`

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

2. `uv init`

用于创建新 Python 项目的骨架。它将生成 pyproject.toml、 .python-version、README.md、示例代码、.gitignore 等文件。

2.1. 基本用法

在当前目录初始化：

uv init

创建新目录及初始化：

uv init my-project

指定 Python 版本：

uv init my-project --python 3.10

常见下一步是：

cd my-project
uv sync
uv run python main.py

uv sync 将创建 .venv 并且安装依赖，uv run 将在该项目环境里运行命令。

2.2. `--app`：应用项目

--app 是默认行为，所以下面两个命令基本等价：

uv init my-app
uv init --app my-app

适合：

训练脚本

数据处理脚本

Web 服务

CLI 工具

内部应用

不打算发布到 PyPI 的项目

典型结构类似：

my-app/
  pyproject.toml
  .python-version
  README.md
  main.py

pyproject.toml 类似：

[project]
name = "my-app"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.10"
dependencies = []

运行：

uv run python main.py

添加依赖：

uv add requests

然后代码里可以：

import requests

应用项目默认不是 package。也就是说，uv sync 主要安装它的依赖，不将当前项目本身作为可 import / 可 build 的包安装进环境。

2.3. `--lib`：库项目

创建库：

uv init --lib my-lib

适合：

写可以被别人 import 的 Python 库

打算发布到 PyPI

希望项目本身能被 uv build 打包

希望使用标准 src/ 布局

典型结构类似：

my-lib/
  pyproject.toml
  .python-version
  README.md
  src/
    my_lib/
      __init__.py

注意包名转换：项目名 my-lib 通常对应 import 包名 my_lib。

pyproject.toml 包含 Build System，比如：

[project]
name = "my-lib"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.10"
dependencies = []

[build-system]
requires = ["uv_build>=0.11.8,<0.12.0"]
build-backend = "uv_build"

使用方式：

uv sync
uv run python -c "import my_lib; print(my_lib)"

构建 wheel/sdist：

uv build

这将生成类似：

dist/
  my_lib-0.1.0-py3-none-any.whl
  my_lib-0.1.0.tar.gz

--lib 生成的项目可 import、可复用、可打包、有 src/ 目录。

2.4. `--package`：使项目可被打包/安装

将当前项目本身当作 Python package 处理。

它将使项目包含 [build-system]，uv sync 时 uv 将当前项目也构建及安装到虚拟环境里，而不是只安装依赖。

重要区别：

uv init --app my-app

默认是应用，不一定是 package。

uv init --app --package my-cli

这是应用，也是 package。适合发布 CLI 的情况。

比如：

uv init --app --package greet-cli

生成类似结构：

greet-cli/
  pyproject.toml
  src/
    greet_cli/
      __init__.py

pyproject.toml 里将有类似：

[project.scripts]
greet-cli = "greet_cli:main"

安装后可以直接运行命令：

uv run greet-cli

也可以构建：

uv build

3. 设置 PyPI 源

uv 设置 PyPI 源主要有三种方式：临时命令行参数、环境变量、写进 pyproject.toml/配置文件。

3.1. 临时指定 PyPI 源

使用清华源：

uv sync --index-url https://pypi.tuna.tsinghua.edu.cn/simple

添加依赖时指定：

uv add requests --index-url https://pypi.tuna.tsinghua.edu.cn/simple

运行 uv pip install 时指定：

uv pip install numpy --index-url https://pypi.tuna.tsinghua.edu.cn/simple

3.2. 通过环境变量设置

在当前 Shell 临时生效：

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

然后运行：

uv sync
uv add requests
uv pip install numpy

都将默认使用该 Index。

如果想保留额外源：

export UV_EXTRA_INDEX_URL=https://download.pytorch.org/whl/cu128

3.3. 写进 `pyproject.toml`

可以在项目里配置 Index：

[[tool.uv.index]]
name = "tuna"
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true

然后 uv sync 将使用该默认源。

如果是额外源，比如 PyTorch CUDA wheel：

[[tool.uv.index]]
name = "pytorch-cu128"
url = "https://download.pytorch.org/whl/cu128"
explicit = true

[tool.uv.sources]
torch = [
    { index = "pytorch-cu128", marker = "sys_platform == 'linux'" },
]
torchvision = [
    { index = "pytorch-cu128", marker = "sys_platform == 'linux'" },
]

explicit = true 是指该源不作为通用 PyPI 源使用，只有在 [tool.uv.sources] 明确指定某个包用它时才会用。

3.4. 用户级全局配置

可以写到 uv 配置文件。macOS/Linux 通常是：

mkdir -p ~/.config/uv

创建或编辑：

# ~/.config/uv/uv.toml
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"

以后所有项目默认使用该源。

4. `uv sync`

根据 pyproject.toml 创建或更新 .venv，安装 [project].dependencies。如果没有 uv.lock，它将先解析依赖，并且生成 lock 文件。

安装项目依赖 + 开发依赖：

uv sync --all-extras

假如pyproject.toml 中包含：

[project.optional-dependencies]
dev = [
    "boto3",
    "ruff",
    "ipython",
    "pytest",
    "pytest-timeout",
    "build",
    "pre-commit",
]

那么该项目的 extra 只有 dev，里面包括 pytest、ruff、pre-commit、ipython 等。等价地也可以写：

uv sync --extra dev

运行项目里的命令，不必手动 source .venv/bin/activate：

uv run python -m pytest tests/ -m "not gpu" -v --timeout=300

5. Python 版本相关

安装 Python 3.12：

uv python install 3.12

用 Python 3.12 创建虚拟环境：

uv venv --python 3.12

同步依赖：

uv sync --all-extras

查看 uv 可用的 Python：

uv python list

6. 依赖锁定

生成或更新 uv.lock：

uv lock

只检查 lock 文件是否已经和 pyproject.toml 一致，不修改文件：

uv lock --locked

如果修改 pyproject.toml 但没更新 lock，该命令将失败，适合 CI 检查。

7. 增删依赖

添加运行时依赖：

uv add package-name

它将修改 pyproject.toml，更新 lock。

添加开发依赖到 dev extra：

uv add --optional dev package-name

移除依赖：

uv remove package-name

如果是 Optional Dependency：

uv remove --optional dev package-name

8. 查看环境

查看已安装包：

uv pip list

查看依赖树：

uv tree

查看某个包为什么被安装：

uv tree --package torch

9. 构建项目