UV使用指南：比 pip 快 10-100 倍的Python项目包管理工具，内附全部命令和配置参数说明

船长Q

已于 2025-04-20 23:20:18 修改

阅读量1.2k

点赞数 36

分类专栏： Python 生产工具 🚀 文章标签： uv pip python

于 2025-04-20 23:16:31 首次发布

本文链接：https://blog.csdn.net/weixin_47339916/article/details/147377535

版权

Python 生产工具 🚀 专栏收录该内容

28 篇文章

订阅专栏

UV使用指南：比 pip 快 10-100 倍的Python项目包管理工具，内附全部命令和配置参数说明

UV 是由 Astral 团队开发的一款用 Rust 编写的 Python 包和项目管理器，目标是成为“Python 的 “Cargo”。它集成了 pip、pip-tools、pipx、poetry、pyenv、twine 和 virtualenv 等工具的功能。

一、核心特性

多工具集成：替代 pip/pip-tools/virtualenv/poetry 等工具链
兼容性强：支持 pyproject.toml、requirements.txt，兼容现有 Python 生态工具链。
极速安装：Rust 实现比 pip 快 ‼️10-100‼️ 倍。🚀🚀🚀
确定性构建：通过 uv.lock 文件保证跨环境一致性
跨平台支持：完整支持 Linux/macOS/Windows

二、环境初始化

# 创建新项目
mkdir my_project && cd my_project
uv venv  # 创建虚拟环境
uv init  # 生成标准项目结构

生成的标准项目结构：

.
├── .venv
│   ├── bin
│   ├── lib
│   ├── share
│   ├── .gitignore
│   ├── CACHEDIR.TAG
│   └── pyvenv.cfg
├── .gitignore
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock

三、`pyproject.toml` 基础示例

[project]
name            = "my-project"
version         = "0.1.0"
description     = "Add your description here"
readme          = "README.md"
requires-python = ">=3.10"
authors         = [{ name = "name", email = "email@example.com" }]

# 主依赖声明
dependencies = ["matplotlib>=3.10.1", "numpy>=2.2.5", "pandas>=2.2.3"]

# 可选依赖
[dependency-groups]
dev = ["black>=25.1.0", "pytest>=8.3.5"]
ml = [
    "scikit-learn>=1.6.1",
    "torch>=2.6.0",
    "torchaudio>=2.6.0",
    "torchvision>=0.21.0",
]

# UV 扩展配置
[[tool.uv.index]]
url     = "https://pypi.tuna.tsinghua.edu.cn/simple" # 镜像源
proxy   = "http://127.0.0.1:1080"                    # 网络代理
default = true

四、命令使用方法说明

`uv run`

用途：运行一个命令或脚本。
使用方法：
```
uv run [OPTIONS] [COMMAND]
```
说明：确保命令在 Python 环境中运行。如果命令是一个以 .py 结尾的文件或 HTTP(S) 链接，文件将被当作脚本运行。如果命令包含内联依赖元数据，这些依赖将被安装到一个临时环境中。

`uv init`

用途：创建一个新项目。
使用方法：
```
uv init [OPTIONS] PATH
```
说明：遵循 pyproject.toml 规范。如果目标路径已存在 pyproject.toml 文件，uv 将退出并报错。如果父目录中存在 pyproject.toml，新项目将被添加为工作区成员。

`uv add`

用途：向项目添加依赖。

使用方法：

uv add [OPTIONS] <PACKAGES|--requirements <REQUIREMENTS>>

说明：将依赖添加到项目的 pyproject.toml 文件中。如果依赖已存在，将更新为新版本约束，除非使用了 --frozen 选项。

`uv remove`

用途：从项目中移除依赖。
使用方法：
```
uv remove [OPTIONS] <PACKAGES>...
```
说明：从项目的 pyproject.toml 文件中移除依赖。如果依赖不存在，uv 将退出并报错。

`uv sync`

用途：更新项目的环境。
使用方法：
```
uv sync [OPTIONS]
```
说明：确保项目环境中的依赖与 uv.lock 文件一致。如果虚拟环境不存在，将创建它。

`uv lock`

用途：更新项目的锁文件。
使用方法：
```
uv lock [OPTIONS]
```
说明：如果锁文件不存在，将创建它。如果锁文件已存在，其内容将作为解析的偏好。

`uv export`

用途：将项目的锁文件导出为其他格式。
使用方法：
```
uv export [OPTIONS]
```
说明：目前仅支持导出为 requirements.txt 格式。

`uv tree`

用途：显示项目的依赖树。
使用方法：
```
uv tree [OPTIONS]
```
说明：显示项目及其依赖的层级结构。

`uv tool`

用途：运行和安装由 Python 包提供的命令。
子命令：
- uv tool run：运行一个由 Python 包提供的命令。
- uv tool install：安装工具。
- uv tool upgrade：升级已安装的工具。
- uv tool list：列出已安装的工具。
- uv tool uninstall：卸载工具。
- uv tool update-shell：确保工具可执行目录在 PATH 中。
- uv tool dir：显示工具目录的路径。

`uv python`

用途：管理 Python 版本和安装。
子命令：
- uv python list：列出可用的 Python 安装。
- uv python install：下载并安装 Python 版本。
- uv python find：搜索 Python 安装。
- uv python pin：固定到特定的 Python 版本。
- uv python dir：显示 uv 的 Python 安装目录。
- uv python uninstall：卸载 Python 版本。

`uv pip`

用途：以 pip 兼容的接口管理 Python 包。
子命令：
- uv pip compile：编译 requirements.in 文件为 requirements.txt 文件。
- uv pip sync：同步环境与 requirements.txt 文件。
- uv pip install：安装包到环境中。
- uv pip uninstall：从环境中卸载包。
- uv pip freeze：以要求格式列出环境中安装的包。
- uv pip list：以表格格式列出环境中安装的包。
- uv pip show：显示一个或多个已安装包的信息。
- uv pip tree：显示环境的依赖树。
- uv pip check：验证已安装包的依赖是否兼容。

`uv venv`

用途：创建虚拟环境。
使用方法：
```
uv venv [OPTIONS] [PATH]
```
说明：默认在当前工作目录中创建名为 .venv 的虚拟环境。如果目标路径已存在虚拟环境，将被移除并重新创建。

`uv build`

用途：构建 Python 包为源分发和轮文件。
使用方法：
```
uv build [OPTIONS] [SRC]
```
说明：默认从目录构建源分发和轮文件。可以使用 --sdist 和 --wheel 选项分别构建。

`uv publish`

用途：将分发文件上传到索引。
使用方法：
```
uv publish [OPTIONS] [FILES]...
```
说明：默认上传 dist 目录中的文件。可以指定文件路径或使用通配符。

`uv cache`

用途：管理 uv 的缓存。
子命令：
- uv cache clean：清除缓存。
- uv cache prune：修剪缓存中不可达的对象。
- uv cache dir：显示缓存目录。

`uv self`

用途：管理 uv 可执行文件。
子命令：
- uv self update：更新 uv。

`uv version`

用途：显示 uv 的版本。
使用方法：
```
uv version
```

`uv generate-shell-completion`

用途：生成 shell 补全脚本。

使用方法：

uv generate-shell-completion [OPTIONS] <SHELL>

`uv help`

用途：显示命令的文档。
使用方法：
```
uv help [OPTIONS] [COMMAND]...
```

四、`pyproject.toml` 配置说明

Project metadata

`build-constraint-dependencies`

类型：list[str]
默认值：[]
说明：用于限制构建依赖版本的约束。当构建包时，这些约束会限制所选的构建依赖版本。它不会触发包的安装，而是确保在构建过程中满足特定版本要求。

示例：

[tool.uv]
build-constraint-dependencies = ["setuptools==60.0.0"]

`conflicts`

类型：list[list[dict]]
默认值：[]
说明：声明冲突的额外依赖或依赖组。当某些额外依赖或依赖组的依赖项相互冲突时，可以通过此配置明确指出，从而避免在安装时出现冲突。

示例：

[tool.uv]
conflicts = [
    [
        { extra = "extra1" },
        { extra = "extra2" },
    ],
    [
        { group = "group1" },
        { group = "group2" },
    ]
]

`constraint-dependencies`

类型：list[str]
默认值：[]
说明：用于限制项目依赖版本的约束。它不会触发包的安装，而是确保在解析依赖时满足特定版本要求。

示例：

[tool.uv]
constraint-dependencies = ["grpcio<1.65"]

`default-groups`

类型：str | list[str]
默认值：["dev"]
说明：指定默认安装的依赖组。可以设置为 "all" 来安装所有组。
示例：
```
[tool.uv]
default-groups = ["docs"]
```

`dev-dependencies`

类型：list[str]
默认值：[]
说明：项目的开发依赖。这些依赖在 uv run 和 uv sync 中默认安装，但不会出现在项目的发布元数据中。建议使用 dependency-groups.dev 替代此字段。

示例：

[tool.uv]
dev-dependencies = ["ruff==0.5.0"]

`environments`

类型：str | list[str]
默认值：[]
说明：指定支持的环境，用于解析依赖。可以通过限制环境来提高性能并避免解析空间中的不可满足分支。

示例：

[tool.uv]
environments = ["sys_platform == 'darwin'"]

`index`

类型：dict
默认值：[]
说明：指定解析依赖时使用的索引。可以指定符合 PEP 503 的仓库或本地目录。索引的优先级由定义顺序决定。

示例：

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"

`managed`

类型：bool
默认值：true
说明：是否由 uv 管理项目。如果设置为 false，uv 在运行时会忽略该项目。
示例：
```
[tool.uv]
managed = false
```

`override-dependencies`

类型：list[str]
默认值：[]
说明：用于覆盖项目依赖的版本。它会强制选择特定版本的包，无论其他包请求的版本是什么。

示例：

[tool.uv]
override-dependencies = ["werkzeug==2.3.0"]

`package`

类型：bool
默认值：true
说明：是否将项目视为 Python 包。如果设置为 false，项目将被视为虚拟项目，不会被构建或安装，仅其依赖项会包含在虚拟环境中。
示例：
```
[tool.uv]
package = false
```

`required-environments`

类型：str | list[str]
默认值：[]
说明：指定项目必须支持的平台。如果某些包没有源码分发版，此配置可以确保解析出的依赖包含特定平台的 wheel。

示例：

[tool.uv]
required-environments = [
    "sys_platform == 'darwin' and platform_machine == 'arm64'",
    "sys_platform == 'darwin' and platform_machine == 'x86_64'",
]

`sources`

类型：dict
默认值：{}
说明：用于解析依赖时的额外来源，可以是 Git 仓库、URL、本地路径或替代仓库。

示例：

[tool.uv.sources]
httpx = { git = "https://github.com/encode/httpx", tag = "0.27.0" }
pytest = { url = "https://files.pythonhosted.org/packages/6b/77/7440a06a8ead44c7757a64362dd22df5760f9b12dc5f11b6188cd2fc27a0/pytest-8.3.3-py3-none-any.whl" }
pydantic = { path = "/path/to/pydantic", editable = true }

`workspace`

子配置：
- exclude：排除作为工作区成员的包。
- members：包含作为工作区成员的包。
类型：list[str]
默认值：[]
说明：用于定义工作区成员，支持 glob 和显式路径。

示例：

[tool.uv.workspace]
exclude = ["member1", "path/to/member2", "libs/*"]
members = ["member1", "path/to/member2", "libs/*"]

Configuration

`allow-insecure-host`

类型：list[str]
默认值：[]
说明：允许与指定主机进行不安全的连接。可以指定主机名、主机端口对或 URL。警告：使用此选项会绕过 SSL 验证，可能会导致中间人攻击。

示例：

[tool.uv]
allow-insecure-host = ["localhost:8080"]

`cache-dir`

类型：str
默认值：None（默认路径为 $XDG_CACHE_HOME/uv 或 $HOME/.cache/uv 或 %LOCALAPPDATA%\uv\cache）
说明：指定缓存目录的路径。
示例：
```
[tool.uv]
cache-dir = "./.uv_cache"
```

`cache-keys`

类型：list[dict]
默认值：[{ file = "pyproject.toml" }, { file = "setup.py" }, { file = "setup.cfg" }]
说明：指定触发项目重建的文件或目录。支持文件、目录、Git 提交信息和环境变量。

示例：

[tool.uv]
cache-keys = [{ file = "pyproject.toml" }, { file = "requirements.txt" }, { git = { commit = true } }]

`check-url`

类型：str
默认值：None
说明：在上传前检查索引 URL 中是否已存在相同文件，以避免重复上传。

示例：

[tool.uv]
check-url = "https://test.pypi.org/simple"

`compile-bytecode`

类型：bool
默认值：false
说明：在安装后编译 Python 文件为字节码。默认情况下，字节码会在模块首次导入时懒加载编译。
示例：
```
[tool.uv]
compile-bytecode = true
```

`concurrent-builds`

类型：int
默认值：None（默认为可用 CPU 核心数）
说明：同时构建源分发包的最大数量。
示例：
```
[tool.uv]
concurrent-builds = 4
```

`concurrent-downloads`

类型：int
默认值：50
说明：同时下载的最大数量。
示例：
```
[tool.uv]
concurrent-downloads = 4
```

`concurrent-installs`

类型：int
默认值：None（默认为可用 CPU 核心数）
说明：安装和解压包时使用的线程数。
示例：
```
[tool.uv]
concurrent-installs = 4
```

`config-settings`

类型：dict
默认值：{}
说明：传递给 PEP 517 构建后端的配置设置。

示例：

[tool.uv]
config-settings = { editable_mode = "compat" }

`dependency-metadata`

类型：list[dict]
默认值：[]
说明：为依赖项提供预定义的静态元数据。支持 name、version、requires-dist、requires-python 和 provides-extras 字段。

示例：

[tool.uv]
dependency-metadata = [
    { name = "flask", version = "1.0.0", requires-dist = ["werkzeug"], requires-python = ">=3.6" }
]

`exclude-newer`

类型：str
默认值：None
说明：限制候选包的上传时间，只选择在指定时间之前的包。支持 RFC 3339 时间戳和本地日期。
示例：
```
[tool.uv]
exclude-newer = "2006-12-02"
```

`extra-index-url`

类型：list[str]
默认值：[]
说明：额外的包索引 URL，优先级高于 index-url 或 index 中的默认索引。

示例：

[tool.uv]
extra-index-url = ["https://download.pytorch.org/whl/cpu"]

`find-links`

类型：list[str]
默认值：[]
说明：额外的候选分发包位置，可以是本地目录或包含包文件链接的网页。

示例：

[tool.uv]
find-links = ["https://download.pytorch.org/whl/torch_stable.html"]

`fork-strategy`

类型：str
默认值："requires-python"
说明：在不同 Python 版本和平台上选择多个版本的包时的策略。可选值为 "fewest"（选择最少版本）和 "requires-python"（选择最新版本）。
示例：
```
[tool.uv]
fork-strategy = "fewest"
```

`index`

类型：dict
默认值：[]
说明：指定解析依赖时使用的包索引。支持 PEP 503 兼容的仓库或本地目录。索引的优先级由定义顺序决定。

示例：

[[tool.uv.index]]
name = "pytorch"
url = "https://download.pytorch.org/whl/cu121"

`index-strategy`

类型：str
默认值："first-index"
说明：在多个索引 URL 中解析时的策略。可选值为 "first-index"（仅使用第一个索引的结果）、"unsafe-first-match" 和 "unsafe-best-match"。

示例：

[tool.uv]
index-strategy = "unsafe-best-match"

`index-url`

类型：str
默认值："https://pypi.org/simple"
说明：默认的 Python 包索引 URL。优先级低于 extra-index-url 或 index 中的索引。

示例：

[tool.uv]
index-url = "https://test.pypi.org/simple"

`keyring-provider`

类型：str
默认值："disabled"
说明：是否使用 keyring 提供身份验证。目前仅支持 subprocess 模式。

示例：

[tool.uv]
keyring-provider = "subprocess"

`link-mode`

类型：str
默认值："clone"（macOS）或 "hardlink"（Linux 和 Windows）
说明：从全局缓存安装包时使用的方法。可选值为 "clone"、"copy"、"hardlink" 和 "symlink"。
示例：
```
[tool.uv]
link-mode = "copy"
```

`native-tls`

类型：bool
默认值：false
说明：是否从平台的原生证书库加载 TLS 证书。默认情况下，使用内置的 webpki-roots 证书。
示例：
```
[tool.uv]
native-tls = true
```

`no-binary`

类型：bool
默认值：false
说明：不安装预构建的 wheel 包，而是从源码构建和安装。
示例：
```
[tool.uv]
no-binary = truef"]
```

`no-binary-package`

类型：list[str]
默认值：[]
说明：指定某些包不使用预构建的 wheel，而是从源码构建和安装。
示例：
```
[tool.uv]
no-binary-package = ["ruff"]
```

`no-build`

类型：bool
默认值：false
说明：不构建源分发包。启用后，解析过程不会运行任意 Python 代码，而是直接使用缓存的 wheel。
示例：
```
[tool.uv]
no-build = true
```

`no-build-isolation`

类型：bool
默认值：false
说明：在构建源分发包时禁用隔离。假设 PEP 518 指定的构建依赖已经安装。
示例：
```
[tool.uv]
no-build-isolation = true
```

`no-build-isolation-package`

类型：list[str]
默认值：[]
说明：为特定包禁用构建隔离。假设这些包的 PEP 518 构建依赖已经安装。

示例：

[tool.uv]
no-build-isolation-package = ["package1", "package2"]

`no-build-package`

类型：list[str]
默认值：[]
说明：不构建特定包的源分发包。
示例：
```
[tool.uv]
no-build-package = ["ruff"]
```

`no-cache`

类型：bool
默认值：false
说明：不使用缓存，而是使用临时目录进行操作。
示例：
```
[tool.uv]
no-cache = true
```

`no-index`

类型：bool
默认值：false
说明：忽略所有注册表索引（例如 PyPI），仅依赖于直接 URL 依赖项和通过 --find-links 提供的依赖项。
示例：
```
[tool.uv]
no-index = true
```

`no-sources`

类型：bool
默认值：false
说明：忽略 tool.uv.sources 表中的依赖来源，仅使用标准的、可发布的包元数据。
示例：
```
[tool.uv]
no-sources = true
```

`offline`

类型：bool
默认值：false
说明：禁用网络访问，仅依赖于本地缓存数据和本地文件。
示例：
```
[tool.uv]
offline = true
```

`prerelease`

类型：str
默认值："if-necessary-or-explicit"
说明：预发布版本的策略。可选值包括：
- "disallow"：禁止所有预发布版本
- "allow"：允许所有预发布版本
- "if-necessary"：如果包的所有版本都是预发布版本，则允许
- "explicit"：仅允许显式标记为预发布的包
- "if-necessary-or-explicit"：如果包的所有版本都是预发布版本，或者包的版本要求中显式标记为预发布，则允许
示例：
```
[tool.uv]
prerelease = "allow"
```

`preview`

类型：bool
默认值：false
说明：是否启用实验性功能。
示例：
```
[tool.uv]
preview = true
```

`publish-url`

类型：str
默认值："https://upload.pypi.org/legacy/"
说明：发布包到 Python 包索引的 URL。

示例：

[tool.uv]
publish-url = "https://test.pypi.org/legacy/"

`pypy-install-mirror`

类型：str
默认值：None
说明：用于下载 PyPy 安装的镜像 URL。默认情况下，从 downloads.python.org 下载。

示例：

[tool.uv]
pypy-install-mirror = "https://downloads.python.org/pypy"

`python-downloads`

类型：str
默认值："automatic"
说明：是否允许下载 Python。可选值包括：
- "automatic"：自动下载所需的 Python 安装
- "manual"：需要手动安装 Python
- "never"：禁止下载 Python
示例：
```
[tool.uv]
python-downloads = "manual"
```

`python-install-mirror`

类型：str
默认值：None
说明：用于下载 Python 安装的镜像 URL。默认情况下，从 python-build-standalone 下载。

示例：

[tool.uv]
python-install-mirror = "https://github.com/astral-sh/python-build-standalone/releases/download"

`python-preference`

类型：str
默认值："managed"
说明：是否优先使用已安装的系统 Python，还是由 uv 下载和安装的 Python。可选值包括：
- "only-managed"：仅使用由 uv 管理的 Python 安装
- "managed"：优先使用由 uv 管理的 Python 安装
- "system"：优先使用系统 Python 安装
- "only-system"：仅使用系统 Python 安装

示例：

[tool.uv]
python-preference = "managed"

`reinstall`

类型：bool
默认值：false
说明：重新安装所有包，无论它们是否已经安装。此选项会隐式启用 refresh。
示例：
```
[tool.uv]
reinstall = true
```

`reinstall-package`

类型：list[str]
默认值：[]
说明：重新安装特定包，无论它们是否已经安装。此选项会隐式启用 refresh-package。
示例：
```
[tool.uv]
reinstall-package = ["ruff"]
```

`required-version`

类型：str
默认值：null
说明：强制 uv 的版本要求。如果运行时 uv 的版本不符合要求，将退出并报错。
示例：
```
[tool.uv]
required-version = ">=0.5.0"
```

`resolution`

类型：str
默认值："highest"
说明：解析依赖时选择兼容版本的策略。可选值包括：
- "highest"：选择最高兼容版本
- "lowest"：选择最低兼容版本
- "lowest-direct"：直接依赖选择最低兼容版本，间接依赖选择最高兼容版本
示例：
```
[tool.uv]
resolution = "lowest-direct"
```

`trusted-publishing`

类型：str
默认值："automatic"
说明：在 GitHub Actions 中配置可信发布。默认情况下，uv 会在 GitHub Actions 中检查可信发布。

示例：

[tool.uv]
trusted-publishing = "always"

`upgrade`

类型：bool
默认值：false
说明：是否允许升级包，忽略现有输出文件中的固定版本。
示例：
```
[tool.uv]
upgrade = true
```

`upgrade-package`

类型：list[str]
默认值：[]
说明：允许升级特定包，忽略现有输出文件中的固定版本。可以指定包名或版本范围。

示例：

[tool.uv]
upgrade-package = ["ruff<0.5.0"]

`pip`

类型：dict
默认值：{}（具体配置项见下文）
说明：uv pip 命令行界面的特定设置。这些设置仅在 uv pip 命令中生效。

`all-extras`

类型：bool
默认值：false
说明：是否包含所有可选依赖项。仅适用于 pyproject.toml、setup.py 和 setup.cfg 源。
示例：
```
[tool.uv.pip]
all-extras = true
```

`allow-empty-requirements`

类型：bool
默认值：false
说明：是否允许 uv pip sync 使用空的依赖项，这将清除环境中的所有包。

示例：

[tool.uv.pip]
allow-empty-requirements = true

`annotation-style`

类型：str
默认值："split"
说明：在输出文件中注释的样式。可选值为 "line"（单行注释）和 "split"（每行一个注释）。

示例：

[tool.uv.pip]
annotation-style = "line"

`break-system-packages`

类型：bool
默认值：false
说明：是否允许修改 EXTERNALLY-MANAGED 的 Python 安装。仅在 CI 环境中推荐使用。

示例：

[tool.uv.pip]
break-system-packages = true

`compile-bytecode`

类型：bool
默认值：false
说明：是否在安装后编译 Python 文件为字节码。默认情况下，字节码会在模块首次导入时懒加载编译。
示例：
```
[tool.uv.pip]
compile-bytecode = true
```

`config-settings`

类型：dict
默认值：{}
说明：传递给 PEP 517 构建后端的配置设置。

示例：

[tool.uv.pip]
config-settings = { editable_mode = "compat" }

`custom-compile-command`

类型：str
默认值：None
说明：在 uv pip compile 生成的输出文件顶部添加的自定义编译命令。

示例：

[tool.uv.pip]
custom-compile-command = "./custom-uv-compile.sh"

`dependency-metadata`

类型：list[dict]
默认值：[]
说明：为依赖项提供预定义的静态元数据。

示例：

[tool.uv.pip]
dependency-metadata = [
    { name = "flask", version = "1.0.0", requires-dist = ["werkzeug"], requires-python = ">=3.6" }
]

`emit-build-options`**

类型：bool
默认值：false
说明：是否在 uv pip compile 生成的输出文件中包含 --no-binary 和 --only-binary 选项。
示例：

[tool.uv.pip]
emit-build-options = true

`emit-find-links`

类型：bool
默认值：false
说明：是否在 uv pip compile 生成的输出文件中包含 --find-links 选项。
示例：
```
[tool.uv.pip]
emit-find-links = true
```

`emit-index-annotation`

类型：bool
默认值：false
说明：是否在 uv pip compile 生成的输出文件中包含索引注释。

示例：

[tool.uv.pip]
emit-index-annotation = true

`emit-index-url`

类型：bool
默认值：false
说明：是否在 uv pip compile 生成的输出文件中包含 --index-url 和 --extra-index-url 选项。
示例：
```
[tool.uv.pip]
emit-index-url = true
```

`emit-marker-expression`

类型：bool
默认值：false
说明：是否在输出文件中包含标记表达式，指示依赖项有效的条件。

示例：

[tool.uv.pip]
emit-marker-expression = true

`exclude-newer`

类型：str
默认值：None
说明：限制候选包的上传时间，仅选择在指定时间之前的包。

示例：

[tool.uv.pip]
exclude-newer = "2006-12-02T02:07:43Z"

`extra`

类型：list[str]
默认值：[]
说明：包含的可选依赖项。仅适用于 pyproject.toml、setup.py 和 setup.cfg 源。
示例：
```
[tool.uv.pip]
extra = ["dev", "docs"]
```

`extra-index-url`

类型：list[str]
默认值：[]
说明：额外的包索引 URL，优先级高于 index-url。

示例：

[tool.uv.pip]
extra-index-url = ["https://download.pytorch.org/whl/cpu"]

`find-links`

类型：list[str]
默认值：[]
说明：额外的候选分发包位置，可以是本地目录或包含包文件链接的网页。

示例：

[tool.uv.pip]
find-links = ["https://download.pytorch.org/whl/torch_stable.html"]

`fork-strategy`

类型：str
默认值："requires-python"
说明：在不同 Python 版本和平台上选择多个版本的包时的策略。
示例：
```
[tool.uv.pip]
fork-strategy = "fewest"
```

`generate-hashes`

类型：bool
默认值：false
说明：是否在输出文件中包含分发包的哈希值。
示例：
```
[tool.uv.pip]
generate-hashes = true
```

`group`

类型：list[str]
默认值：None
说明：指定要包含的依赖组。
示例：
```
[tool.uv.pip]
group = ["dev", "docs"]
```

`index-strategy`

类型：str
默认值："first-index"
说明：在多个索引 URL 中解析时的策略。可选值为：
- "first-index"：仅使用第一个索引的结果。
- "unsafe-first-match"：在所有索引中搜索每个包名，优先使用第一个索引中的版本。
- "unsafe-best-match"：在所有索引中搜索每个包名，选择最佳版本。

示例：

[tool.uv.pip]
index-strategy = "unsafe-best-match"

`index-url`

类型：str
默认值："https://pypi.org/simple"
说明：Python 包索引的 URL。此设置的优先级低于 extra-index-url。

示例：

[tool.uv.pip]
index-url = "https://test.pypi.org/simple"

`keyring-provider`

类型：str
默认值："disabled"
说明：是否使用 keyring 提供身份验证。目前仅支持 subprocess 模式。

示例：

[tool.uv.pip]
keyring-provider = "subprocess"

`link-mode`

类型：str
默认值："clone"（macOS）或 "hardlink"（Linux 和 Windows）
说明：从全局缓存安装包时使用的方法。可选值为：
- "clone"：使用 Copy-on-Write 模式。
- "copy"：复制包。
- "hardlink"：创建硬链接。
- "symlink"：创建符号链接。
示例：
```
[tool.uv.pip]
link-mode = "copy"
```

`no-annotate`

类型：bool
默认值：false
说明：是否在 uv pip compile 生成的输出文件中排除注释。
示例：
```
[tool.uv.pip]
no-annotate = true
```

`no-binary`

类型：list[str]
默认值：[]
说明：指定不使用预构建的 wheel 包，而是从源码构建和安装。可以指定包名或 :all:（禁用所有包的二进制安装）。
示例：
```
[tool.uv.pip]
no-binary = ["ruff"]
```

`no-build`

类型：bool
默认值：false
说明：是否禁用源分发包的构建。启用后，解析过程不会运行任意 Python 代码。
示例：
```
[tool.uv.pip]
no-build = true
```

`no-build-isolation`

类型：bool
默认值：false
说明：是否禁用构建源分发包时的隔离。假设 PEP 518 指定的构建依赖已经安装。

示例：

[tool.uv.pip]
no-build-isolation = true

`no-build-isolation-package`

类型：list[str]
默认值：[]
说明：为特定包禁用构建隔离。假设这些包的 PEP 518 构建依赖已经安装。

示例：

[tool.uv.pip]
no-build-isolation-package = ["package1", "package2"]

`no-deps`

类型：bool
默认值：false
说明：是否忽略包的依赖项，仅添加显式列出的包到结果依赖文件中。
示例：
```
[tool.uv.pip]
no-deps = true
```

`no-emit-package`

类型：list[str]
默认值：[]
说明：指定要从输出解析中省略的包。其依赖项仍将包含在解析中。

示例：

[tool.uv.pip]
no-emit-package = ["ruff"]

`no-extra`

类型：list[str]
默认值：[]
说明：如果启用了 all-extras，则排除指定的可选依赖项。

示例：

[tool.uv.pip]
all-extras = true
no-extra = ["dev", "docs"]

`no-header`

类型：bool
默认值：false
说明：是否排除 uv pip compile 生成的输出文件顶部的注释头。
示例：
```
[tool.uv.pip]
no-header = true
```

`no-index`

类型：bool
默认值：false
说明：是否忽略所有注册表索引（例如 PyPI），仅依赖于直接 URL 依赖项和通过 --find-links 提供的依赖项。
示例：
```
[tool.uv.pip]
no-index = true
```

`no-sources`

类型：bool
默认值：false
说明：是否忽略 tool.uv.sources 表中的依赖来源，仅使用标准的、可发布的包元数据。
示例：
```
[tool.uv.pip]
no-sources = true
```

`no-strip-extras`

类型：bool
默认值：false
说明：是否在输出文件中保留可选依赖项。默认情况下，可选依赖项会被移除。
示例：
```
[tool.uv.pip]
no-strip-extras = true
```

`no-strip-markers`

类型：bool
默认值：false
说明：是否在输出文件中保留环境标记。默认情况下，环境标记会被移除。
示例：
```
[tool.uv.pip]
no-strip-markers = true
```

`only-binary`

类型：list[str]
默认值：[]
说明：仅使用预构建的 wheel 包，不从源码构建。可以指定包名或 :all:（仅使用所有包的二进制安装）。
示例：
```
[tool.uv.pip]
only-binary = ["ruff"]
```

`output-file`

类型：str
默认值：None
说明：指定 uv pip compile 生成的依赖文件的输出路径。如果文件已存在，将优先使用现有版本进行解析，除非同时指定了 --upgrade。

示例：

[tool.uv.pip]
output-file = "requirements.txt"

`prefix`

类型：str
默认值：None
说明：指定安装包的目标目录，类似于虚拟环境的结构。不推荐使用，因为安装的脚本将引用安装解释器，而不是目标目录中的解释器。
示例：
```
[tool.uv.pip]
prefix = "./prefix"
```

`prerelease`

类型：str
默认值："if-necessary-or-explicit"
说明：预发布版本的策略。可选值包括：
- "disallow"：禁止所有预发布版本。
- "allow"：允许所有预发布版本。
- "if-necessary"：如果包的所有版本都是预发布版本，则允许。
- "explicit"：仅允许显式标记为预发布的包。
- "if-necessary-or-explicit"：如果包的所有版本都是预发布版本，或者包的版本要求中显式标记为预发布，则允许。
示例：
```
[tool.uv.pip]
prerelease = "allow"
```

`python`

类型：str
默认值：None
说明：指定安装包的目标 Python 解释器。支持以下格式：
- 3.10：查找已安装的 Python 3.10（Windows 上的注册表或 Linux/macOS 上的 python3.10）。
- python3.10 或 python.exe：在 PATH 中查找指定名称的二进制文件。
- /home/ferris/.local/bin/python3.10：使用指定路径的 Python。
示例：
```
[tool.uv.pip]
python = "3.10"
```

`python-platform`

类型：str
默认值：None
说明：指定解析依赖的目标平台，格式为“目标三元组”，例如 x86_64-unknown-linux-gnu 或 aarch64-apple-darwin。

示例：

[tool.uv.pip]
python-platform = "x86_64-unknown-linux-gnu"

`python-version`

类型：str
默认值：None
说明：指定解析依赖时支持的最低 Python 版本，例如 3.8 或 3.8.17。如果省略补丁版本，则假定为最低补丁版本，例如 3.8 表示 3.8.0。
示例：
```
[tool.uv.pip]
python-version = "3.8"
```

`reinstall`

类型：bool
默认值：false
说明：是否重新安装所有包，无论它们是否已经安装。此选项隐式启用 refresh。
示例：
```
[tool.uv.pip]
reinstall = true
```

`reinstall-package`

类型：list[str]
默认值：[]
说明：重新安装特定包，无论它们是否已经安装。此选项隐式启用 refresh-package。

示例：

[tool.uv.pip]
reinstall-package = ["ruff"]

`require-hashes`

类型：bool
默认值：false
说明：是否要求每个依赖项都提供匹配的哈希值。启用后，所有依赖项都必须提供哈希值，并且必须是固定版本（例如 ==1.0.0）或通过直接 URL 指定。
示例：
```
[tool.uv.pip]
require-hashes = true
```

`resolution`

类型：str
默认值："highest"
说明：解析依赖时选择兼容版本的策略。可选值包括：
- "highest"：选择最高兼容版本。
- "lowest"：选择最低兼容版本。
- "lowest-direct"：直接依赖选择最低兼容版本，间接依赖选择最高兼容版本。

示例：

[tool.uv.pip]
resolution = "lowest-direct"

`strict`

类型：bool
默认值：false
说明：是否验证 Python 环境，检测缺少依赖项和其他问题。
示例：
```
[tool.uv.pip]
strict = true
```

`system`

类型：bool
默认值：false
说明：是否将包安装到系统 Python 环境中。默认情况下，uv 会安装到当前工作目录或父目录中的虚拟环境中。
示例：
```
[tool.uv.pip]
system = true
```

`target`

类型：str
默认值：None
说明：指定将包安装到的目标目录，而不是安装到虚拟环境或系统 Python 环境中。包将安装到目录的顶层。
示例：
```
[tool.uv.pip]
target = "./target"
```

`torch-backend`

类型：str
默认值：null
说明：指定 PyTorch 生态系统中使用的后端。可选值包括：
- cpu：使用 CPU-only 的 PyTorch 索引。
- cu126：使用 CUDA 12.6 的 PyTorch 索引。
- auto：自动检测当前安装的 CUDA 驱动程序并选择合适的 PyTorch 索引。
示例：
```
[tool.uv.pip]
torch-backend = "auto"
```

`universal`

类型：bool
默认值：false
说明：是否执行通用解析，尝试生成一个兼容所有操作系统、架构和 Python 实现的单一 requirements.txt 文件。在通用模式下，当前 Python 版本（或用户指定的 --python-version）将被视为下限。
示例：
```
[tool.uv.pip]
universal = true
```

`upgrade`

类型：bool
默认值：false
说明：是否允许升级包，忽略现有输出文件中的固定版本。
示例：
```
[tool.uv.pip]
upgrade = true
```

`upgrade-package`

类型：list[str]
默认值：[]
说明：允许升级特定包，忽略现有输出文件中的固定版本。可以指定包名或版本范围。

示例：

[tool.uv.pip]
upgrade-package = ["ruff<0.5.0"]

`verify-hashes`

类型：bool
默认值：true
说明：是否验证要求文件中提供的哈希值。与 require-hashes 不同，此选项不会要求所有依赖项都提供哈希值，而是仅验证那些提供了哈希值的依赖项。
示例：
```
[tool.uv.pip]
verify-hashes = true
```

UV使用指南：比 pip 快 10-100 倍的Python项目包管理工具，内附全部命令和配置参数说明

UV使用指南：比 pip 快 10-100 倍的Python项目包管理工具，内附全部命令和配置参数说明

一、核心特性

二、环境初始化

三、pyproject.toml 基础示例

四、命令使用方法说明

uv run

uv init

uv add

uv remove

uv sync

uv lock

uv export

uv tree

uv tool

uv python

uv pip

uv venv

uv build

uv publish

uv cache

uv self

uv version

uv generate-shell-completion

uv help

四、pyproject.toml 配置说明

Project metadata

build-constraint-dependencies

conflicts

constraint-dependencies

default-groups

dev-dependencies

environments

index

managed

override-dependencies

package

required-environments

sources

workspace

Configuration

allow-insecure-host

cache-dir

cache-keys

check-url

compile-bytecode

concurrent-builds

concurrent-downloads

concurrent-installs

config-settings

dependency-metadata

exclude-newer

extra-index-url

find-links

fork-strategy

index

index-strategy

index-url

keyring-provider

link-mode

native-tls

no-binary

no-binary-package

no-build

no-build-isolation

no-build-isolation-package

no-build-package

no-cache

no-index

no-sources

offline

prerelease

preview

publish-url

pypy-install-mirror

python-downloads

python-install-mirror

python-preference

reinstall

reinstall-package

三、`pyproject.toml` 基础示例

`uv run`

`uv init`

`uv add`

`uv remove`

`uv sync`

`uv lock`

`uv export`

`uv tree`

`uv tool`

`uv python`

`uv pip`

`uv venv`

`uv build`

`uv publish`

`uv cache`

`uv self`

`uv version`

`uv generate-shell-completion`

`uv help`

四、`pyproject.toml` 配置说明

`build-constraint-dependencies`

`conflicts`

`constraint-dependencies`

`default-groups`

`dev-dependencies`

`environments`

`index`

`managed`

`override-dependencies`

`package`

`required-environments`

`sources`

`workspace`

`allow-insecure-host`

`cache-dir`

`cache-keys`

`check-url`

`compile-bytecode`

`concurrent-builds`

`concurrent-downloads`

`concurrent-installs`

`config-settings`

`dependency-metadata`

`exclude-newer`

`extra-index-url`

`find-links`

`fork-strategy`

`index`

`index-strategy`

`index-url`

`keyring-provider`

`link-mode`

`native-tls`

`no-binary`

`no-binary-package`

`no-build`

`no-build-isolation`

`no-build-isolation-package`

`no-build-package`

`no-cache`

`no-index`

`no-sources`

`offline`

`prerelease`

`preview`

`publish-url`

`pypy-install-mirror`

`python-downloads`

`python-install-mirror`

`python-preference`

`reinstall`

`reinstall-package`

`required-version`

`resolution`

`trusted-publishing`

`upgrade`

`upgrade-package`

`pip`

`all-extras`