设置

项目元数据

`build-constraint-dependencies`

解决构建依赖时应用的约束（constraints）。

构建约束用于限制在构建包时（解析或安装期间）所选用的构建依赖的版本。

将某个包作为约束包含进来，并不会在构建过程中自动安装该包；相反，必须在项目的构建依赖图的其他地方显式请求该包。

Note

在 uv lock、uv sync 和 uv run 命令中，uv 只会读取工作区根目录下 pyproject.toml 文件中的 build-constraint-dependencies，并忽略其他工作区成员或 uv.toml 文件中的相关声明。

默认值: []

类型: list[str]

示例用法:

pyproject.toml

[tool.uv]
# 确保当某个包有 setuptools 构建依赖时，总是使用 setuptools v60.0.0。
build-constraint-dependencies = ["setuptools==60.0.0"]

`conflicts`

声明一组 extras 或依赖分组（dependency groups）之间存在冲突（即互斥）。

当两个或多个 extras 之间存在互不兼容的依赖时，声明冲突会很有用。例如，extra foo 可能依赖于 numpy==2.0.0，而 extra bar 依赖于 numpy==2.1.0。虽然这些依赖存在冲突，但用户通常不会同时激活 foo 和 bar，因此仍有可能为项目生成一个通用的依赖解析结果。

通过显式声明这些冲突，uv 可以在考虑某些 extras 和分组互斥的情况下，为项目生成通用的依赖解析结果。作为交换，如果用户尝试同时激活冲突的 extras，安装将会失败。

默认值: []

类型: list[list[dict]]

示例用法:

pyproject.toml

[tool.uv]
# 要求 `package[extra1]` 和 `package[extra2]` 在不同分支（fork）中解析，避免相互冲突。
conflicts = [
    [
        { extra = "extra1" },
        { extra = "extra2" },
    ]
]

# 要求依赖分组 `group1` 和 `group2` 在不同分支中解析，避免相互冲突。
conflicts = [
    [
        { group = "group1" },
        { group = "group2" },
    ]
]

`constraint-dependencies`

解析项目依赖时应用的约束（constraints）。

约束用于限制在解析过程中所选用的依赖版本。

将某个包作为约束包含进来，并不会单独触发该包的安装；必须在项目的一方依赖或传递依赖中显式请求该包。

Note

在 uv lock、uv sync 和 uv run 命令中，uv 只会读取工作区根目录下 pyproject.toml 文件中的 constraint-dependencies，并忽略其他工作区成员或 uv.toml 文件中的相关声明。

默认值: []

类型: list[str]

示例用法:

pyproject.toml

[tool.uv]
# 确保当直接或传递依赖请求 grpcio 时，其版本始终小于 1.65。
constraint-dependencies = ["grpcio<1.65"]

`default-groups`

默认安装的 dependency-groups 列表。

也可以设置为字面值 "all"，以默认启用所有分组。

默认值: ["dev"]

类型: str | list[str]

示例用法:

pyproject.toml

[tool.uv]
default-groups = ["docs"]

`dev-dependencies`

项目的开发依赖（development dependencies）。

开发依赖会在 uv run 和 uv sync 中默认安装，但不会出现在项目发布的元数据中。

不再推荐使用该字段。建议使用标准化的 dependency-groups.dev 字段来声明开发依赖。tool.uv.dev-dependencies 和 dependency-groups.dev 的内容会合并，决定最终的 dev 依赖分组需求。

默认值: []

类型: list[str]

示例用法:

pyproject.toml

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

`environments`

用于解析依赖的支持环境（environments）列表。

默认情况下，uv 会在执行 uv lock 操作时为所有可能的环境进行解析。不过，你可以通过限制支持的环境集合来提升性能，并避免在解空间中出现不可满足的分支。

当使用 uv pip compile 并带有 --universal 标志时，这些环境也会被尊重。

默认值: []

类型: str | list[str]

示例用法:

pyproject.toml

[tool.uv]
# 仅为 macOS 解析依赖，不包含 Linux 或 Windows。
environments = ["sys_platform == 'darwin'"]

`index`

解析依赖时使用的索引（indexes）。

可接受符合 PEP 503（simple repository API）的仓库，或以相同格式布局的本地目录。

索引按照定义顺序依次考虑，最先定义的索引优先级最高。此外，通过该设置提供的索引优先级高于通过 index_url 或 extra_index_url 指定的索引。uv 只会考虑第一个包含指定包的索引，除非指定了其他 index strategy。

如果某个索引设置了 explicit = true，则仅当依赖通过 [tool.uv.sources] 显式选择该索引时才会使用，例如：

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

[tool.uv.sources]
torch = { index = "pytorch" }

如果某个索引设置了 default = true，则会被移动到优先级列表的末尾，在解析包时优先级最低。此外，标记为 default 的索引会禁用 PyPI 默认索引。

默认值: []

类型: dict

示例用法:

pyproject.toml

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

`managed`

项目是否由 uv 管理。如果为 false，在执行 uv run 时 uv 会忽略该项目。

默认值: true

类型: bool

示例用法:

pyproject.toml

[tool.uv]
managed = false

`override-dependencies`

解析项目依赖时应用的覆盖（overrides）。

覆盖用于强制选择某个包的特定版本，无论其他包请求的版本如何，也无论选择该版本是否通常会导致无效的解析结果。

约束（constraints）是“叠加”的，即与各个包的需求合并；而覆盖（overrides）是“绝对”的，即完全替换任何相关包的需求。

将某个包作为覆盖包含进来，并不会单独触发该包的安装；必须在项目的一方依赖或传递依赖中显式请求该包。

Note

在 uv lock、uv sync 和 uv run 命令中，uv 只会读取工作区根目录下 pyproject.toml 文件中的 override-dependencies，并忽略其他工作区成员或 uv.toml 文件中的相关声明。

默认值: []

类型: list[str]

示例用法:

pyproject.toml

[tool.uv]
# 无论传递依赖请求哪个版本，总是安装 Werkzeug 2.3.0。
override-dependencies = ["werkzeug==2.3.0"]

`package`

项目是否应被视为 Python 包，或非包（“虚拟”项目）。

包会以可编辑模式（editable mode）构建并安装到虚拟环境中，因此需要构建后端（build backend）；而虚拟项目不会被构建或安装，仅将其依赖包含进虚拟环境。

创建包要求 pyproject.toml 中存在 build-system，并且项目结构需符合构建后端的预期（如 src 布局）。

默认值: true

类型: bool

示例用法:

pyproject.toml

[tool.uv]
package = false

`required-environments`

针对缺少源码分发包（source distribution）的包，指定所需平台（platforms）列表。

当某个包没有源码分发包时，其可用性将受限于其已发布的构建分发包（wheel）所支持的平台。例如，如果某个包只发布了 Linux 的 wheel，那么它无法在 macOS 或 Windows 上安装。

默认情况下，uv 要求每个包至少包含一个与指定 Python 版本兼容的 wheel。可以通过 required-environments 设置，确保最终解析结果包含特定平台的 wheel，否则解析失败。

environments 设置会限制 uv 解析依赖时考虑的环境集合，而 required-environments 会扩展 uv 在解析依赖时必须支持的平台集合。

例如，environments = ["sys_platform == 'darwin'"] 会让 uv 只为 macOS 解析（忽略 Linux 和 Windows）；而 required-environments = ["sys_platform == 'darwin'"] 则要求任何没有源码分发包的包，必须包含 macOS 的 wheel，才能被安装。

默认值: []

类型: str | list[str]

示例用法:

pyproject.toml

[tool.uv]
# 要求包同时支持 macOS ARM 和 x86（Intel）。
required-environments = [
    "sys_platform == 'darwin' and platform_machine == 'arm64'",
    "sys_platform == 'darwin' and platform_machine == 'x86_64'",
]

`sources`

用于解析依赖时指定的源（sources）。

tool.uv.sources 用于为依赖元数据补充额外的来源，这些来源会在开发过程中被引入。依赖源可以是 Git 仓库、URL、本地路径或其他注册表（registry）。

更多内容详见依赖（Dependencies）。

默认值: {}

类型: dict

示例用法:

pyproject.toml

[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 }

`build-backend`

uv 构建后端（uv_build）的相关设置。

Note

uv 构建后端目前处于预览阶段，未来版本可能会有变更。

请注意，这些设置仅在使用 uv_build 构建后端时生效，其他构建后端（如 hatchling）有各自的配置方式。

所有支持 glob 的选项均采用 PEP 639 中定义的可移植 glob 模式。

每个条目为一个目录，其内容会被复制到 wheel 包中对应的 <name>-<version>.data/(purelib|platlib|headers|scripts|data) 目录下。安装时，这些数据会被移动到其目标位置，具体规则见 https://docs.python.org/3.12/library/sysconfig.html#installation-paths。通常，小型数据文件建议直接放在 Python 模块内，而不是通过 data includes 方式。

scripts：安装到可执行文件目录，Unix 下为 <venv>/bin，Windows 下为 <venv>\Scripts。该目录会在虚拟环境激活或使用 uv run 时加入 PATH，因此可用于安装额外的二进制文件。对于 Python 入口点，建议优先使用 project.scripts。
data：覆盖安装到虚拟环境根目录。

警告：此操作可能会覆盖已有文件！
headers：安装到 include 目录。编译依赖该包的 Python 包时，编译器会在 include 目录查找额外的头文件。
purelib 和 platlib：安装到 site-packages 目录。不推荐使用这两个选项。

默认值: {}

类型: dict[str, str]

示例用法:

pyproject.toml

[tool.uv.build-backend]
data = { "headers": "include/headers", "scripts": "bin" }

`default-excludes`

如设置为 false，则不会应用默认排除项。

默认排除项包括：__pycache__、*.pyc 和 *.pyo。

默认值: true

类型: bool

示例用法:

pyproject.toml

[tool.uv.build-backend]
default-excludes = false

`module-name`

module-root 目录下模块目录的名称。

默认模块名为包名，将其中的点（.）和短横线（-）替换为下划线（_）。

注意：使用该选项可能导致出现两个不同包名但模块名相同的包。如果同时安装这类包，可能会出现未定义行为，常见问题包括文件或目录树损坏。

默认值: None

类型: str

示例用法:

pyproject.toml

[tool.uv.build-backend]
module-name = "sklearn"

`module-root`

常见取值为 src（src 布局，默认）或空路径（扁平布局）。

默认值: "src"

类型: str

示例用法:

pyproject.toml

[tool.uv.build-backend]
module-root = ""

`source-exclude`

用于排除源分发包（source distribution）中指定文件和目录的 glob 表达式。

默认值: []

类型: list[str]

示例用法:

pyproject.toml

[tool.uv.build-backend]
source-exclude = ["*.bin"]

`source-include`

用于额外包含到源分发包中的文件和目录的 glob 表达式。

pyproject.toml 及模块目录内容始终会被包含。

默认值: []

类型: list[str]

示例用法:

pyproject.toml

[tool.uv.build-backend]
source-include = ["tests/**"]

`wheel-exclude`

用于排除 wheel 包中指定文件和目录的 glob 表达式。

默认值: []

类型: list[str]

示例用法:

pyproject.toml

[tool.uv.build-backend]
wheel-exclude = ["*.bin"]

`workspace`

`exclude`

需要从工作区成员中排除的包。如果某个包同时匹配 members 和 exclude，则会被排除。

支持 glob 模式和显式路径。

有关 glob 语法的更多信息，请参阅 glob 文档。

默认值: []

类型: list[str]

示例用法:

pyproject.toml

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

`members`

需要包含为工作区成员的包。

支持 glob 模式和显式路径。

有关 glob 语法的更多信息，请参阅 glob 文档。

默认值: []

类型: list[str]

示例用法:

pyproject.toml

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

配置

`allow-insecure-host`

允许与主机建立不安全连接。

可接受主机名（如 localhost）、主机端口对（如 localhost:8080）或 URL（如 https://localhost）。

警告：该列表中的主机不会通过系统证书存储进行校验。仅在受信任的安全网络环境下使用 --allow-insecure-host，否则会绕过 SSL 校验，可能导致中间人攻击（MITM）。

默认值: []

类型: list[str]

示例用法:

pyproject.tomluv.toml

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

allow-insecure-host = ["localhost:8080"]

`cache-dir`

缓存目录的路径。

Linux 和 macOS 下默认值为 $XDG_CACHE_HOME/uv 或 $HOME/.cache/uv，Windows 下为 %LOCALAPPDATA%\uv\cache。

默认值: None

类型: str

示例用法:

pyproject.tomluv.toml

[tool.uv]
cache-dir = "./.uv_cache"

cache-dir = "./.uv_cache"

`cache-keys`

用于项目构建缓存的关键项（cache keys）。

通过设置缓存关键项，可以指定哪些文件或目录的变动会触发项目的重新构建。默认情况下，只要项目目录下的 pyproject.toml、setup.py 或 setup.cfg 文件被修改，或者 src 目录被添加或移除，uv 就会重新构建项目，例如：

cache-keys = [{ file = "pyproject.toml" }, { file = "setup.py" }, { file = "setup.cfg" }, { dir = "src" }]

例如：如果项目通过动态元数据（dynamic metadata）从 requirements.txt 文件读取依赖，可以指定 cache-keys = [{ file = "requirements.txt" }, { file = "pyproject.toml" }]，这样每当 requirements.txt 文件发生变动时（以及监控 pyproject.toml），项目都会被重新构建。

支持 glob 通配符，语法遵循 glob crate。例如，如果希望只要项目目录或其任意子目录下的 .toml 文件发生变动就使缓存失效，可以指定 cache-keys = [{ file = "**/*.toml" }]。注意，使用 glob 可能会带来性能开销，因为 uv 需要遍历文件系统以判断文件是否发生变化。

缓存关键项还可以包含版本控制信息。例如，如果项目通过 setuptools_scm 从 Git 提交（commit）读取版本号，可以指定 cache-keys = [{ git = { commit = true }, { file = "pyproject.toml" }]，这样缓存关键项中会包含当前 Git 提交哈希（commit hash）（以及 pyproject.toml）。也支持通过 cache-keys = [{ git = { commit = true, tags = true } }] 包含 Git 标签（tag）。

缓存关键项还可以包含环境变量。例如，如果项目依赖 MACOSX_DEPLOYMENT_TARGET 或其他环境变量来决定其行为，可以指定 cache-keys = [{ env = "MACOSX_DEPLOYMENT_TARGET" }]，这样每当该环境变量变化时缓存就会失效。

缓存关键项只影响定义它们的 pyproject.toml 所在的项目（不会影响工作区 workspace 的其他成员），所有路径和 glob 都是相对于项目目录进行解析。

默认值: [{ file = "pyproject.toml" }, { file = "setup.py" }, { file = "setup.cfg" }]

类型: list[dict]

示例用法:

pyproject.tomluv.toml

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

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

`check-url`

检查索引 URL 是否已存在文件，以跳过重复上传。

该选项允许在部分文件上传成功、部分失败的情况下重试发布，并处理并发上传同一文件导致的错误。

在上传前，会先检查索引。如果索引中已存在完全相同的文件，则不会再次上传该文件。如果上传过程中发生错误，会再次检查索引，以处理并发上传同一文件的情况。

具体行为会根据索引不同而有所差异。在上传到 PyPI 时，即使不加 --check-url，重复上传同一文件也会成功，而大多数其他索引会报错。

索引必须提供受支持的哈希算法之一（SHA-256、SHA-384 或 SHA-512）。

默认值: None

类型: str

示例用法:

pyproject.tomluv.toml

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

check-url = "https://test.pypi.org/simple"

`compile-bytecode`

安装后将 Python 文件编译为字节码（bytecode）。

默认情况下，uv 不会将 Python（.py）文件编译为字节码（__pycache__/*.pyc）；而是在模块首次被导入时按需（懒加载）编译。对于启动速度要求较高的场景（如 CLI 应用、Docker 容器），可以启用该选项，以牺牲安装时间换取更快的启动速度。

启用后，uv 会处理整个 site-packages 目录（包括本次操作未修改的包），以保证一致性。与 pip 一样，编译过程中会忽略错误。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv]
compile-bytecode = true

compile-bytecode = true

`concurrent-builds`

uv 同时并发构建的源码分发包（source distribution）最大数量。

默认值为可用 CPU 核心数。

默认值: None

类型: int

示例用法:

pyproject.tomluv.toml

[tool.uv]
concurrent-builds = 4

concurrent-builds = 4

`concurrent-downloads`

uv 同时进行的最大并发下载数。

默认值: 50

类型: int

示例用法:

pyproject.tomluv.toml

[tool.uv]
concurrent-downloads = 4

concurrent-downloads = 4

`concurrent-installs`

安装和解压包时使用的线程数。

默认值为可用 CPU 核心数。

默认值: None

类型: int

示例用法:

pyproject.tomluv.toml

[tool.uv]
concurrent-installs = 4

concurrent-installs = 4

`config-settings`

传递给 PEP 517 构建后端的设置，以 KEY=VALUE 形式指定。

默认值: {}

类型: dict

示例用法:

pyproject.tomluv.toml

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

config-settings = { editable_mode = "compat" }

`dependency-metadata`

为项目的依赖（直接或间接）预定义静态元数据。当提供该项时，解析器会使用指定的元数据，而不是从注册表查询或从源码构建相关包。

元数据应遵循 Metadata 2.3 标准，但仅支持以下字段：

name：包名。
（可选）version：包版本。如果省略，则该元数据应用于该包的所有版本。
（可选）requires-dist：包的依赖（如 werkzeug>=0.14）。
（可选）requires-python：包所需的 Python 版本（如 >=3.10）。
（可选）provides-extras：包提供的 extras。

默认值: []

类型: list[dict]

示例用法:

pyproject.tomluv.toml

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

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

`exclude-newer`

限制候选包为在指定日期之前上传的版本。

支持 RFC 3339 时间戳（如 2006-12-02T02:07:43Z）和本地日期（如 2006-12-02，使用系统配置的时区）。

默认值: None

类型: str

示例用法:

pyproject.tomluv.toml

[tool.uv]
exclude-newer = "2006-12-02"

exclude-newer = "2006-12-02"

`extra-index-url`

除 --index-url 外，额外使用的包索引（index）URL。

可接受符合 PEP 503（simple repository API）的仓库，或以相同格式布局的本地目录。

通过该参数提供的所有索引优先级高于通过 index_url 或带 default = true 的 index 指定的索引。多个索引时，前面的优先级更高。

如需控制 uv 在多个索引下的解析策略，请参见 index_strategy。

（已废弃：建议使用 index。）

默认值: []

类型: list[str]

示例用法:

pyproject.tomluv.toml

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

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

`find-links`

除注册表索引外，额外搜索候选分发包的位置。

如果为路径，目标必须是包含包的目录，包以 wheel 文件（.whl）或源码分发包（如 .tar.gz 或 .zip）形式存放在顶层目录。

如果为 URL，页面必须包含指向上述格式包文件的扁平链接列表。

默认值: []

类型: list[str]

示例用法:

pyproject.tomluv.toml

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

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

`fork-strategy`

选择在不同 Python 版本和平台下为同一个包选取多个版本时所采用的策略。

默认情况下，uv 会针对每个受支持的 Python 版本（requires-python），优先选择该包的最新版本，同时尽量减少跨平台所需的版本数量。

当设置为 fewest 时，uv 会尽可能减少每个包被选中的版本数量，优先选择兼容更多 Python 版本或平台的较旧版本。

默认值: "requires-python"

可选值:

"fewest"：优化为每个包选择最少的版本数量。如果某个较旧版本能兼容更多 Python 版本或平台，则可能优先选用较旧版本
"requires-python"：针对每个受支持的 Python 版本，优先选择每个包的最新受支持版本

示例用法:

pyproject.tomluv.toml

[tool.uv]
fork-strategy = "fewest"

fork-strategy = "fewest"

`index`

解析依赖时使用的包索引（index）。

可接受符合 PEP 503（simple repository API）的仓库，或以相同格式布局的本地目录。

索引会按照定义顺序依次考虑，最先定义的索引优先级最高。此外，通过该设置提供的索引优先级高于通过 index_url 或 extra_index_url 指定的索引。uv 只会考虑第一个包含指定包的索引，除非指定了其他 index strategy。

如果某个索引设置了 explicit = true，则仅当依赖通过 [tool.uv.sources] 显式选择该索引时才会使用，例如：

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

[tool.uv.sources]
torch = { index = "pytorch" }

如果某个索引设置了 default = true，则会被移动到优先级列表的末尾，在解析包时优先级最低。此外，标记为 default 的索引会禁用 PyPI 默认索引。

默认值: "[]"

类型: dict

示例用法:

pyproject.tomluv.toml

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

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

`index-strategy`

解析多个索引（index）URL 时采用的策略。

默认情况下，uv 会在第一个包含指定包的索引处停止，并仅在该索引中解析该包（first-index）。这样可以防止“依赖混淆（dependency confusion）”攻击，即攻击者在其他索引上传同名恶意包。

默认值: "first-index"

可选值:

"first-index"：只使用第一个返回匹配包名的索引中的结果
"unsafe-first-match"：对每个包名遍历所有索引，先用第一个索引的所有版本，耗尽后再查找下一个索引
"unsafe-best-match"：对每个包名遍历所有索引，优先选择找到的“最佳”版本。如果某个包版本在多个索引中都存在，只考虑第一个索引的条目

示例用法:

pyproject.tomluv.toml

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

index-strategy = "unsafe-best-match"

`index-url`

Python 包索引（index）的 URL（默认值：https://pypi.org/simple）。

可接受符合 PEP 503（simple repository API）的仓库，或以相同格式布局的本地目录。

通过该设置指定的索引优先级低于通过 extra_index_url 或 index 指定的索引。

（已废弃：建议使用 index。）

默认值: "https://pypi.org/simple"

类型: str

示例用法:

pyproject.tomluv.toml

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

index-url = "https://test.pypi.org/simple"

`keyring-provider`

尝试使用 keyring 进行索引 URL 的身份认证。

目前仅支持 --keyring-provider subprocess，即 uv 通过 keyring 命令行工具处理认证。

默认值: "disabled"

类型: str

示例用法:

pyproject.tomluv.toml

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

keyring-provider = "subprocess"

`link-mode`

从全局缓存安装包时所采用的方式。

在 macOS 上默认使用 clone（即 Copy-on-Write），在 Linux 和 Windows 上默认使用 hardlink。

默认值: "clone" (macOS) 或 "hardlink" (Linux, Windows)

可选值:

"clone"：以“克隆”（Copy-on-Write）方式将 wheel 包内容复制到 site-packages 目录
"copy"：直接复制 wheel 包内容到 site-packages 目录
"hardlink"：以硬链接方式将 wheel 包内容链接到 site-packages 目录
"symlink"：以符号链接方式将 wheel 包内容链接到 site-packages 目录

示例用法:

pyproject.tomluv.toml

[tool.uv]
link-mode = "copy"

link-mode = "copy"

`native-tls`

是否从平台的原生证书存储加载 TLS 证书。

默认情况下，uv 从自带的 webpki-roots crate 加载证书。webpki-roots 基于 Mozilla 的可信根证书，内置可提升 uv 的可移植性和性能（尤其是在 macOS 上）。

但在某些场景下，如果你依赖于系统证书存储中的企业根证书（如强制代理），可以启用该选项以使用平台原生证书存储。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv]
native-tls = true

native-tls = true

`no-binary`

不安装预构建的 wheel 包。

指定的包将从源码构建并安装。解析器仍会优先使用预构建 wheel 提取包元数据（如有）。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv]
no-binary = true

no-binary = true

`no-binary-package`

为指定包不安装预构建的 wheel 包。

默认值: []

类型: list[str]

示例用法:

pyproject.tomluv.toml

[tool.uv]
no-binary-package = ["ruff"]

no-binary-package = ["ruff"]

`no-build`

不构建源码分发包（source distribution）。

启用后，解析过程中不会运行任何 Python 代码。已构建的源码分发包会复用缓存的 wheel，若需构建则直接报错。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv]
no-build = true

no-build = true

`no-build-isolation`

构建源码分发包时不启用隔离环境。

假定 PEP 518 指定的构建依赖已预先安装。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

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

no-build-isolation = true

`no-build-isolation-package`

为指定包构建源码分发包时不启用隔离环境。

假定这些包的 PEP 518 构建依赖已预先安装。

默认值: []

类型: list[str]

示例用法:

pyproject.tomluv.toml

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

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

`no-build-package`

为指定包不构建源码分发包。

默认值: []

类型: list[str]

示例用法:

pyproject.tomluv.toml

[tool.uv]
no-build-package = ["ruff"]

no-build-package = ["ruff"]

`no-cache`

避免读取或写入缓存，操作期间将使用一个临时目录。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv]
no-cache = true

no-cache = true

`no-index`

忽略所有注册表索引（如 PyPI），仅依赖于直接 URL 依赖和通过 --find-links 提供的依赖。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv]
no-index = true

no-index = true

`no-sources`

解析依赖时忽略 tool.uv.sources 表。用于基于标准兼容、可发布的包元数据进行锁定，而不是使用任何本地或 Git 源。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv]
no-sources = true

no-sources = true

`offline`

禁用网络访问，仅依赖本地缓存的数据和本地可用的文件。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv]
offline = true

offline = true

`prerelease`

选择处理预发布版本（pre-release）时采用的策略。

默认情况下，uv 会接受仅发布预发布版本的包，以及在声明的版本约束中显式包含预发布标记的第一方依赖（if-necessary-or-explicit）。

默认值: "if-necessary-or-explicit"

可选值:

"disallow"：禁止所有预发布版本
"allow"：允许所有预发布版本
"if-necessary"：仅当某个包所有版本都是预发布时才允许预发布版本
"explicit"：仅对第一方依赖中显式包含预发布标记的版本约束允许预发布版本
"if-necessary-or-explicit"：仅当某个包所有版本都是预发布，或依赖中显式包含预发布标记时允许预发布版本

示例用法:

pyproject.tomluv.toml

[tool.uv]
prerelease = "allow"

prerelease = "allow"

`preview`

是否启用实验性、预览功能。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv]
preview = true

preview = true

`publish-url`

用于发布包到 Python 包索引（package index）的 URL（默认值：https://upload.pypi.org/legacy/）。

默认值: "https://upload.pypi.org/legacy/"

类型: str

示例用法:

pyproject.tomluv.toml

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

publish-url = "https://test.pypi.org/legacy/"

`pypy-install-mirror`

用于下载托管 PyPy 安装包的镜像（mirror）URL。

默认情况下，托管的 PyPy 安装包会从 downloads.python.org 下载。可以通过该变量设置为其他镜像源。提供的 URL 会替换如 https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2 中的 https://downloads.python.org/pypy。

也可以通过 file:// URL 方案从本地目录读取分发包。

默认值: None

类型: str

示例用法:

pyproject.tomluv.toml

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

pypy-install-mirror = "https://downloads.python.org/pypy"

`python-downloads`

是否允许下载 Python 解释器。

默认值: "automatic"

可选值:

"automatic"：按需自动下载托管 Python 解释器
"manual"：不自动下载托管 Python 解释器，需手动安装
"never"：禁止下载 Python 解释器

示例用法:

pyproject.tomluv.toml

[tool.uv]
python-downloads = "manual"

python-downloads = "manual"

`python-downloads-json-url`

指向自定义 Python 解释器安装信息 JSON 文件的 URL。

注意：目前仅支持本地路径。

默认值: None

类型: str

示例用法:

pyproject.tomluv.toml

[tool.uv]
python-downloads-json-url = "/etc/uv/python-downloads.json"

python-downloads-json-url = "/etc/uv/python-downloads.json"

`python-install-mirror`

用于下载托管 Python 解释器的镜像（mirror）URL。

默认情况下，托管 Python 解释器会从 python-build-standalone 下载。可以通过该变量设置为其他镜像源。提供的 URL 会替换如 https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz 中的 https://github.com/astral-sh/python-build-standalone/releases/download。

也可以通过 file:// URL 方案从本地目录读取分发包。

默认值: None

类型: str

示例用法:

pyproject.tomluv.toml

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

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

`python-preference`

优先使用系统已存在的 Python 解释器，还是 uv 下载和安装的托管 Python 解释器。

默认值: "managed"

可选值:

"only-managed"：仅使用托管 Python 解释器，不使用系统 Python
"managed"：优先使用托管 Python 解释器
"system"：优先使用系统 Python 解释器
"only-system"：仅使用系统 Python，不使用托管 Python

示例用法:

pyproject.tomluv.toml

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

python-preference = "managed"

`reinstall`

重新安装所有包，无论其是否已安装。隐式启用 refresh。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv]
reinstall = true

reinstall = true

`reinstall-package`

重新安装指定包，无论其是否已安装。隐式启用 refresh-package。

默认值: []

类型: list[str]

示例用法:

pyproject.tomluv.toml

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

reinstall-package = ["ruff"]

`required-version`

强制要求 uv 的版本满足指定条件。

如果运行时 uv 的版本不满足要求，uv 会直接报错并退出。

接受 PEP 440 版本约束，如 ==0.5.0 或 >=0.5.0。

默认值: null

类型: str

示例用法:

pyproject.tomluv.toml

[tool.uv]
required-version = ">=0.5.0"

required-version = ">=0.5.0"

`resolution`

选择满足依赖要求时，针对可用版本的选择策略。

默认情况下，uv 会为每个包选择最新的兼容版本（highest）。

默认值: "highest"

可选值:

"highest"：为每个包解析出最高的兼容版本
"lowest"：为每个包解析出最低的兼容版本
"lowest-direct"：对直接依赖选择最低兼容版本，对传递依赖选择最高兼容版本

示例用法:

pyproject.tomluv.toml

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

resolution = "lowest-direct"

`trusted-publishing`

通过 GitHub Actions 配置可信发布（trusted publishing）。

默认情况下，uv 在 GitHub Actions 环境下会检测可信发布，但如果未配置或 workflow 权限不足（如 fork 的 pull request），则会忽略该功能。

默认值: automatic

类型: str

示例用法:

pyproject.tomluv.toml

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

trusted-publishing = "always"

`upgrade`

允许升级包，忽略现有输出文件中已锁定的版本。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv]
upgrade = true

upgrade = true

`upgrade-package`

允许指定包升级，忽略现有输出文件中已锁定的版本。

可同时接受包名（如 ruff）和带版本约束的包名（如 ruff<0.5.0）。

默认值: []

类型: list[str]

示例用法:

pyproject.tomluv.toml

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

upgrade-package = ["ruff"]

`pip`

uv pip 命令行接口专用的设置项。

这些配置项仅在 uv pip 命名空间下生效（如 uv lock、uvx 等命令不会读取）。

`all-extras`

包含所有可选依赖（optional dependencies）。

仅适用于 pyproject.toml、setup.py 和 setup.cfg 源。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
all-extras = true

[pip]
all-extras = true

`allow-empty-requirements`

允许在 requirements 为空时执行 uv pip sync，此操作会清空环境中的所有包。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

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

[pip]
allow-empty-requirements = true

`annotation-style`

输出文件中注释（annotation）风格，用于标注每个包的来源。

默认值: "split"

可选值:

"line"：将所有注释渲染为一行，使用逗号分隔
"split"：每个注释单独渲染为一行

示例用法:

pyproject.tomluv.toml

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

[pip]
annotation-style = "line"

`break-system-packages`

允许 uv 修改 EXTERNALLY-MANAGED（外部管理）Python 安装环境。

警告：--break-system-packages 主要用于持续集成（CI）环境，在这些环境下，Python 由外部包管理器（如 apt）管理。请谨慎使用，因为此类 Python 安装环境明确建议不要被其他包管理器（如 uv 或 pip）修改。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

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

[pip]
break-system-packages = true

`compile-bytecode`

安装后将 Python 文件编译为字节码（bytecode）。

默认情况下，uv 不会将 Python（.py）文件编译为字节码（__pycache__/*.pyc）；而是在模块首次被导入时按需（懒加载）编译。对于启动速度要求较高的场景（如 CLI 应用、Docker 容器），可以启用该选项，以牺牲安装时间换取更快的启动速度。

启用后，uv 会处理整个 site-packages 目录（包括本次操作未修改的包），以保证一致性。与 pip 一样，编译过程中会忽略错误。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
compile-bytecode = true

[pip]
compile-bytecode = true

`config-settings`

传递给 PEP 517 构建后端的设置，以 KEY=VALUE 形式指定。

默认值: {}

类型: dict

示例用法:

pyproject.tomluv.toml

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

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

`custom-compile-command`

在 uv pip compile 生成的输出文件顶部插入的注释内容。

用于标注自定义构建脚本或包装 uv pip compile 的命令。

默认值: None

类型: str

示例用法:

pyproject.tomluv.toml

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

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

`dependency-metadata`

为项目依赖（直接或间接）预定义静态元数据。当提供该项时，解析器会使用指定的元数据，而不是从注册表查询或从源码构建相关包。

元数据应遵循 Metadata 2.3 标准，但仅支持以下字段：

name：包名。
（可选）version：包版本。如果省略，则该元数据应用于该包的所有版本。
（可选）requires-dist：包的依赖（如 werkzeug>=0.14）。
（可选）requires-python：包所需的 Python 版本（如 >=3.10）。
（可选）provides-extras：包提供的 extras。

默认值: []

类型: list[dict]

示例用法:

pyproject.tomluv.toml

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

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

`emit-build-options`

在 uv pip compile 生成的输出文件中包含 --no-binary 和 --only-binary 配置项。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

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

[pip]
emit-build-options = true

`emit-find-links`

在 uv pip compile 生成的输出文件中包含 --find-links 配置项。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
emit-find-links = true

[pip]
emit-find-links = true

`emit-index-annotation`

在注释中标注每个包解析所用索引（如 # from https://pypi.org/simple）。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

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

[pip]
emit-index-annotation = true

`emit-index-url`

在 uv pip compile 生成的输出文件中包含 --index-url 和 --extra-index-url 配置项。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

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

[pip]
emit-index-url = true

`emit-marker-expression`

是否在输出文件中生成一个 marker 字符串，用于指示当前锁定依赖集（pinned dependencies）在哪些条件下有效。

即使 marker 表达式为 false，锁定依赖集也可能有效；但当表达式为 true 时，可以确定 requirements 是正确的。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

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

[pip]
emit-marker-expression = true

`exclude-newer`

限制候选包为在指定时间点之前上传的版本。

支持 RFC 3339 的超集（如 2006-12-02T02:07:43Z）。为确保解析器在不同时区下行为一致，需提供完整时间戳。

默认值: None

类型: str

示例用法:

pyproject.tomluv.toml

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

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

`extra`

包含指定 extra 的可选依赖（optional dependencies）；可多次指定。

仅适用于 pyproject.toml、setup.py 和 setup.cfg 源。

默认值: []

类型: list[str]

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
extra = ["dev", "docs"]

[pip]
extra = ["dev", "docs"]

`extra-index-url`

除 --index-url 外，额外使用的包索引（index）URL。

可接受符合 PEP 503（simple repository API）的仓库，或以相同格式布局的本地目录。

通过该参数提供的所有索引优先级高于通过 index_url 指定的索引。多个索引时，前面的优先级更高。

如需控制 uv 在多个索引下的解析策略，请参见 index_strategy。

默认值: []

类型: list[str]

示例用法:

pyproject.tomluv.toml

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

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

`find-links`

除注册表索引外，额外搜索候选分发包的位置。

如果为路径，目标必须是包含包的目录，包以 wheel 文件（.whl）或源码分发包（如 .tar.gz 或 .zip）形式存放在顶层目录。

如果为 URL，页面必须包含指向上述格式包文件的扁平链接列表。

默认值: []

类型: list[str]

示例用法:

pyproject.tomluv.toml

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

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

`fork-strategy`

在不同 Python 版本和平台下为同一个包选取多个版本时所采用的策略。

默认情况下，uv 会针对每个受支持的 Python 版本（requires-python），优先选择该包的最新版本，同时尽量减少跨平台所需的版本数量。

当设置为 fewest 时，uv 会尽可能减少每个包被选中的版本数量，优先选择兼容更多 Python 版本或平台的较旧版本。

默认值: "requires-python"

可选值:

"fewest"：优化为每个包选择最少的版本数量。如果某个较旧版本能兼容更多 Python 版本或平台，则可能优先选用较旧版本
"requires-python"：针对每个受支持的 Python 版本，优先选择每个包的最新受支持版本

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
fork-strategy = "fewest"

[pip]
fork-strategy = "fewest"

`generate-hashes`

在输出文件中包含分发包哈希值（distribution hashes）。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
generate-hashes = true

[pip]
generate-hashes = true

`group`

包含以下依赖分组（dependency groups）。

默认值: None

类型: list[str]

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
group = ["dev", "docs"]

[pip]
group = ["dev", "docs"]

`index-strategy`

解析多个索引（index）URL 时采用的策略。

默认情况下，uv 会在第一个包含指定包的索引处停止，并仅在该索引中解析该包（first-index）。这样可以防止“依赖混淆（dependency confusion）”攻击，即攻击者在其他索引上传同名恶意包。

默认值: "first-index"

可选值:

"first-index"：只使用第一个返回匹配包名的索引中的结果
"unsafe-first-match"：对每个包名遍历所有索引，先用第一个索引的所有版本，耗尽后再查找下一个索引
"unsafe-best-match"：对每个包名遍历所有索引，优先选择找到的“最佳”版本。如果某个包版本在多个索引中都存在，只考虑第一个索引的条目

示例用法:

pyproject.tomluv.toml

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

[pip]
index-strategy = "unsafe-best-match"

`index-url`

Python 包索引（index）的 URL（默认值：https://pypi.org/simple）。

可接受符合 PEP 503（simple repository API）的仓库，或以相同格式布局的本地目录。

通过该设置指定的索引优先级低于通过 extra_index_url 指定的索引。

默认值: "https://pypi.org/simple"

类型: str

示例用法:

pyproject.tomluv.toml

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

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

`keyring-provider`

尝试使用 keyring 进行索引 URL 的身份认证。

目前仅支持 --keyring-provider subprocess，即 uv 通过 keyring 命令行工具处理认证。

默认值: disabled

类型: str

示例用法:

pyproject.tomluv.toml

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

[pip]
keyring-provider = "subprocess"

`link-mode`

从全局缓存安装包时所采用的方式。

在 macOS 上默认使用 clone（即 Copy-on-Write），在 Linux 和 Windows 上默认使用 hardlink。

默认值: "clone" (macOS) 或 "hardlink" (Linux, Windows)

可选值:

"clone"：以“克隆”（Copy-on-Write）方式将 wheel 包内容复制到 site-packages 目录
"copy"：直接复制 wheel 包内容到 site-packages 目录
"hardlink"：以硬链接方式将 wheel 包内容链接到 site-packages 目录
"symlink"：以符号链接方式将 wheel 包内容链接到 site-packages 目录

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
link-mode = "copy"

[pip]
link-mode = "copy"

`no-annotate`

在 uv pip compile 生成的输出文件中不包含每个包来源的注释。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
no-annotate = true

[pip]
no-annotate = true

`no-binary`

不安装预构建的 wheel 包。

指定的包将从源码构建并安装。解析器仍会优先使用预构建 wheel 提取包元数据（如有）。

可同时指定多个包。对所有包禁用二进制包可使用 :all:。如需清除之前指定的包可用 :none:。

默认值: []

类型: list[str]

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
no-binary = ["ruff"]

[pip]
no-binary = ["ruff"]

`no-build`

不构建源码分发包（source distribution）。

启用后，解析过程中不会运行任何 Python 代码。已构建的源码分发包会复用缓存的 wheel，若需构建则直接报错。

等价于 --only-binary :all:。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

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

[pip]
no-build = true

`no-build-isolation`

构建源码分发包时不启用隔离环境。

假定 PEP 518 指定的构建依赖已预先安装。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

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

[pip]
no-build-isolation = true

`no-build-isolation-package`

为指定包构建源码分发包时不启用隔离环境。

假定这些包的 PEP 518 构建依赖已预先安装。

默认值: []

类型: list[str]

示例用法:

pyproject.tomluv.toml

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

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

`no-deps`

忽略包依赖，仅将命令行中显式指定的包添加到最终 requirements 文件。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
no-deps = true

[pip]
no-deps = true

`no-emit-package`

指定某个包不出现在输出的依赖解析结果中，但其依赖仍会被包含。等价于 pip-compile 的 --unsafe-package 选项。

默认值: []

类型: list[str]

示例用法:

pyproject.tomluv.toml

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

[pip]
no-emit-package = ["ruff"]

`no-extra`

如已指定 all-extras，则排除指定的可选依赖（optional dependencies）。

默认值: []

类型: list[str]

示例用法:

pyproject.tomluv.toml

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

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

`no-header`

在 uv pip compile 生成的输出文件中不包含顶部注释头部。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
no-header = true

[pip]
no-header = true

`no-index`

忽略所有注册表索引（如 PyPI），仅依赖于直接 URL 依赖和通过 --find-links 提供的依赖。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
no-index = true

[pip]
no-index = true

`no-sources`

解析依赖时忽略 tool.uv.sources 表。用于基于标准兼容、可发布的包元数据进行锁定，而不是使用任何本地或 Git 源。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
no-sources = true

[pip]
no-sources = true

`no-strip-extras`

在输出文件中包含 extras。

默认情况下，uv 会去除 extras，因为通过 extras 引入的所有包已经直接作为依赖包含在输出文件中。此外，使用 --no-strip-extras 生成的输出文件不能作为 install 和 sync 命令的 constraints 文件使用。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
no-strip-extras = true

[pip]
no-strip-extras = true

`no-strip-markers`

在 uv pip compile 生成的输出文件中包含环境标记（environment markers）。

默认情况下，uv 会去除环境标记，因为 compile 生成的解析结果只保证对目标环境是正确的。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
no-strip-markers = true

[pip]
no-strip-markers = true

`only-binary`

仅使用预构建的 wheel 包，不构建源码分发包（source distribution）。

启用后，解析过程中不会运行指定包的任何代码。已构建的源码分发包会复用缓存的 wheel，若需构建则直接报错。

可同时指定多个包。对所有包启用仅二进制可用 :all:，如需清除之前指定的包可用 :none:。

默认值: []

类型: list[str]

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
only-binary = ["ruff"]

[pip]
only-binary = ["ruff"]

`output-file`

将 uv pip compile 生成的 requirements 写入指定的 requirements.txt 文件。

如果该文件已存在，解析依赖时会优先使用已有版本，除非同时指定了 --upgrade。

默认值: None

类型: str

示例用法:

pyproject.tomluv.toml

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

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

`prefix`

将包安装到指定目录下的 lib、bin 等顶层文件夹中，仿佛该位置存在一个虚拟环境（virtual environment）。

通常建议优先使用 --python 安装到其他环境，因为通过 --prefix 安装的脚本和其他产物会引用安装时的解释器，而不是 --prefix 目录下后续添加的解释器，因此不可移植。

默认值: None

类型: str

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
prefix = "./prefix"

[pip]
prefix = "./prefix"

`prerelease`

选择处理预发布版本（pre-release）时采用的策略。

默认情况下，uv 会接受仅发布预发布版本的包，以及在声明的版本约束中显式包含预发布标记的第一方依赖（if-necessary-or-explicit）。

默认值: "if-necessary-or-explicit"

可选值:

"disallow"：禁止所有预发布版本
"allow"：允许所有预发布版本
"if-necessary"：仅当某个包所有版本都是预发布时才允许预发布版本
"explicit"：仅对第一方依赖中显式包含预发布标记的版本约束允许预发布版本
"if-necessary-or-explicit"：仅当某个包所有版本都是预发布，或依赖中显式包含预发布标记时允许预发布版本

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
prerelease = "allow"

[pip]
prerelease = "allow"

`python`

指定用于安装包的 Python 解释器。

默认情况下，uv 会安装到当前工作目录或其父目录中的虚拟环境（virtual environment）。通过 --python 选项可以指定其他解释器，主要用于持续集成（CI）环境或其他自动化流程。

支持的格式： - 3.10：在 Windows 上会在注册表中查找已安装的 Python 3.10（参见 py --list-paths），在 Linux 和 macOS 上查找 python3.10。 - python3.10 或 python.exe：在 PATH 中查找同名可执行文件。 - /home/ferris/.local/bin/python3.10：使用指定路径下的 Python 解释器。

默认值: None

类型: str

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
python = "3.10"

[pip]
python = "3.10"

`python-platform`

指定依赖解析所针对的平台。

以“target triple”（目标三元组）字符串表示，描述目标平台的 CPU、厂商和操作系统名称，例如 x86_64-unknown-linux-gnu 或 aarch64-apple-darwin。

默认值: None

类型: str

示例用法:

pyproject.tomluv.toml

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

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

`python-version`

解析依赖时应支持的最低 Python 版本（如 3.8 或 3.8.17）。

如果省略补丁版本，则默认使用最低补丁版本。例如，3.8 会被映射为 3.8.0。

默认值: None

类型: str

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
python-version = "3.8"

[pip]
python-version = "3.8"

`reinstall`

重新安装所有包，无论其是否已安装。隐式启用 refresh。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
reinstall = true

[pip]
reinstall = true

`reinstall-package`

重新安装指定包，无论其是否已安装。隐式启用 refresh-package。

默认值: []

类型: list[str]

示例用法:

pyproject.tomluv.toml

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

[pip]
reinstall-package = ["ruff"]

`require-hashes`

要求每个依赖项都提供匹配的哈希值。

哈希校验模式为全有或全无。如果启用，所有依赖项都必须提供对应的哈希值或哈希集合。此外，启用后，所有依赖项必须锁定为精确版本（如 ==1.0.0），或通过直接 URL 指定。

哈希校验模式会引入以下额外限制：

不支持 Git 依赖。
不支持可编辑安装（editable installs）。
不支持本地依赖，除非指向特定的 wheel 文件（.whl）或源码归档（.zip、.tar.gz），而不是目录。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
require-hashes = true

[pip]
require-hashes = true

`resolution`

选择满足依赖要求时，针对可用版本的选择策略。

默认情况下，uv 会为每个包选择最新的兼容版本（highest）。

默认值: "highest"

可选值:

"highest"：为每个包解析出最高的兼容版本
"lowest"：为每个包解析出最低的兼容版本
"lowest-direct"：对直接依赖选择最低兼容版本，对传递依赖选择最高兼容版本

示例用法:

pyproject.tomluv.toml

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

[pip]
resolution = "lowest-direct"

`strict`

校验 Python 环境，检测缺失依赖等问题。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
strict = true

[pip]
strict = true

`system`

将包安装到系统 Python 环境中。

默认情况下，uv 会安装到当前工作目录或其父目录中的虚拟环境。--system 选项会让 uv 使用系统 PATH 中找到的第一个 Python。

警告：--system 主要用于持续集成（CI）环境，使用时需谨慎，因为它会修改系统 Python 安装。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
system = true

[pip]
system = true

`target`

将包安装到指定目录，而不是虚拟环境或系统 Python 环境。包会被安装在该目录的顶层。

默认值: None

类型: str

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
target = "./target"

[pip]
target = "./target"

`torch-backend`

指定获取 PyTorch 生态包时使用的后端。

设置后，uv 会忽略 PyTorch 生态包的已配置索引 URL，转而使用指定的后端。

例如，设置为 cpu 时，uv 会使用仅包含 CPU 的 PyTorch 索引；设置为 cu126 时，会使用 CUDA 12.6 的 PyTorch 索引。

auto 模式会尝试根据当前已安装的 CUDA 驱动自动检测合适的 PyTorch 索引。

该选项为预览功能，未来版本可能会变更。

默认值: null

类型: str

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
torch-backend = "auto"

[pip]
torch-backend = "auto"

`universal`

执行通用（universal）依赖解析，尝试生成一个兼容所有操作系统、架构和 Python 实现的 requirements.txt 输出文件。

在通用模式下，当前 Python 版本（或用户指定的 --python-version）会被视为下限。例如，--universal --python-version 3.7 会生成适用于 Python 3.7 及以上版本的通用解析结果。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
universal = true

[pip]
universal = true

`upgrade`

允许升级包，忽略现有输出文件中已锁定的版本。

默认值: false

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
upgrade = true

[pip]
upgrade = true

`upgrade-package`

允许指定包升级，忽略现有输出文件中已锁定的版本。

可同时接受包名（如 ruff）和带版本约束的包名（如 ruff<0.5.0）。

默认值: []

类型: list[str]

示例用法:

pyproject.tomluv.toml

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

[pip]
upgrade-package = ["ruff"]

`verify-hashes`

校验 requirements 文件中已提供的哈希值。

与 --require-hashes 不同，--verify-hashes 不要求所有依赖都包含哈希值；它只会校验那些已包含哈希值的依赖项。

默认值: true

类型: bool

示例用法:

pyproject.tomluv.toml

[tool.uv.pip]
verify-hashes = true

[pip]
verify-hashes = true