设置

项目元数据

`build-constraint-dependencies`

解决构建依赖项时应用的约束。

构建约束用于限制在解决或安装期间构建包时选择的构建依赖项的版本。

将包作为约束包含将不会触发在构建期间安装该包；相反，必须在项目构建依赖项图的其他位置请求该包。

注意

在 uv lock、uv sync 和 uv run 中，uv 将仅从工作区根目录下的 pyproject.toml 中读取 build-constraint-dependencies，并将忽略其他工作区成员或 uv.toml 文件中的任何声明。

默认值: []

类型: list[str]

用法示例:

pyproject.toml

[tool.uv]
# Ensure that the setuptools v60.0.0 is used whenever a package has a build dependency
# on setuptools.
build-constraint-dependencies = ["setuptools==60.0.0"]

`conflicts`

声明冲突的（即互斥的）额外项或依赖项组的集合。

当两个或多个额外项具有互不兼容的依赖项时，声明冲突很有用。例如，额外项 foo 可能依赖于 numpy==2.0.0，而额外项 bar 依赖于 numpy==2.1.0。虽然这些依赖项冲突，但可能用户不希望同时激活 foo 和 bar，因此即使存在不兼容性，也可以为项目生成通用解决方案。

通过显式声明此类冲突，uv 可以为项目生成通用解决方案，同时考虑到某些额外项和组的组合是互斥的。作为交换，如果用户尝试同时激活冲突的额外项，安装将失败。

默认值: []

类型: list[list[dict]]

用法示例:

pyproject.toml

[tool.uv]
# Require that `package[extra1]` and `package[extra2]` are resolved
# in different forks so that they cannot conflict with one another.
conflicts = [
    [
        { extra = "extra1" },
        { extra = "extra2" },
    ]
]

# Require that the dependency groups `group1` and `group2`
# are resolved in different forks so that they cannot conflict
# with one another.
conflicts = [
    [
        { group = "group1" },
        { group = "group2" },
    ]
]

`constraint-dependencies`

解决项目依赖项时应用的约束。

约束用于限制在解决期间选择的依赖项的版本。

将包作为约束包含将不会触发单独安装该包；相反，必须在项目的第一方或传递依赖项的其他位置请求该包。

注意

在 uv lock、uv sync 和 uv run 中，uv 将仅从工作区根目录下的 pyproject.toml 中读取 constraint-dependencies，并将忽略其他工作区成员或 uv.toml 文件中的任何声明。

默认值: []

类型: list[str]

用法示例:

pyproject.toml

[tool.uv]
# Ensure that the grpcio version is always less than 1.65, if it's requested by a
# direct or transitive dependency.
constraint-dependencies = ["grpcio<1.65"]

`default-groups`

默认安装的 dependency-groups 列表。

也可以是字面量 "all" 以默认启用所有组。

默认值: ["dev"]

类型: str | list[str]

用法示例:

pyproject.toml

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

`dependency-groups`

dependency-groups 的其他设置。

目前，这仅可用于向依赖项组添加 requires-python 约束（通常是为了告知 uv 您的开发工具对 Python 的要求高于您的实际项目）。

这不能用于定义依赖项组，请使用顶层 [dependency-groups] 表。

默认值: []

类型: dict

用法示例:

pyproject.toml

[tool.uv.dependency-groups]
my-group = {requires-python = ">=3.12"}

`dev-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`

用于解析依赖项的受支持环境的列表。

默认情况下，uv 将在 uv lock 操作期间解析所有可能的环境。但是，您可以限制受支持环境的集合，以提高性能并避免解决方案空间中出现无法满足的分支。

当使用 --universal 标志调用 uv pip compile 时，也会遵守这些环境。

默认值: []

类型: str | list[str]

用法示例:

pyproject.toml

[tool.uv]
# Resolve for macOS, but not for Linux or Windows.
environments = ["sys_platform == 'darwin'"]

`index`

解决依赖项时要使用的索引。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

索引按照定义的顺序进行考虑，使得首先定义的索引具有最高优先级。此外，此设置提供的索引比通过 index_url 或 extra_index_url 指定的任何索引具有更高的优先级。uv 将仅考虑包含给定包的第一个索引，除非指定了备用索引策略。

如果索引标记为 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，它将被移动到优先级列表的末尾，以便在解决包时给予最低优先级。此外，将索引标记为默认值将禁用 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`

解决项目依赖项时应用的覆盖。

覆盖用于强制选择特定版本的包，而不管任何其他包请求的版本，也无论选择该版本通常是否构成无效解决方案。

虽然约束是附加的，因为它们与构成包的需求相结合，但覆盖是绝对的，因为它们完全替换了任何构成包的需求。

将包作为覆盖包含将不会触发单独安装该包；相反，必须在项目的第一方或传递依赖项的其他位置请求该包。

注意

在 uv lock、uv sync 和 uv run 中，uv 将仅从工作区根目录下的 pyproject.toml 中读取 override-dependencies，并将忽略其他工作区成员或 uv.toml 文件中的任何声明。

默认值: []

类型: list[str]

用法示例:

pyproject.toml

[tool.uv]
# Always install Werkzeug 2.3.0, regardless of whether transitive dependencies request
# a different version.
override-dependencies = ["werkzeug==2.3.0"]

`package`

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

包以可编辑模式构建并安装到虚拟环境中，因此需要构建后端，而虚拟项目不构建或安装；相反，只有它们的依赖项包含在虚拟环境中。

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

默认值: true

类型: bool

用法示例:

pyproject.toml

[tool.uv]
package = false

`required-environments`

缺少源分发的包所需的平台的列表。

当包没有源分发时，它的可用性将受到其构建分发（wheels）支持的平台的限制。例如，如果包仅发布 Linux 的 wheels，则它将无法在 macOS 或 Windows 上安装。

默认情况下，uv 要求每个包至少包含一个与指定的 Python 版本兼容的 wheel。required-environments 设置可用于确保生成的解决方案包含特定平台的 wheels，或者如果无法获得此类 wheels，则会失败。

虽然 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]
# Require that the package is available for macOS ARM and x86 (Intel).
required-environments = [
    "sys_platform == 'darwin' and platform_machine == 'arm64'",
    "sys_platform == 'darwin' and platform_machine == 'x86_64'",
]

`sources`

解决依赖项时要使用的来源。

tool.uv.sources 使用在开发期间合并的其他来源丰富依赖项元数据。依赖项来源可以是 Git 存储库、URL、本地路径或备用注册表。

有关更多信息，请参阅依赖项。

默认值: {}

类型: 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 }

`构建后端`

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

请注意，这些设置仅在使用 uv_build 后端时适用，其他构建后端（例如 hatchling）有自己的配置。

所有接受 Glob 的选项都使用 PEP 639 中的可移植 Glob 模式。

每个条目都是一个目录，其内容将复制到 Wheel 中 <name>-<version>.data/(purelib|platlib|headers|scripts|data) 的匹配目录中。安装时，此数据将移动到目标位置，如 https://docs.pythonlang.cn/3.12/library/sysconfig.html#installation-paths 中定义。通常，通过将小数据文件放置在 Python 模块中而不是使用数据包含来包含它们。

scripts：安装到可执行文件的目录，在 Unix 上为 <venv>/bin，在 Windows 上为 <venv>\Scripts。激活虚拟环境或使用 uv run 时，此目录将添加到 PATH 中，因此可以使用此数据类型来安装其他二进制文件。对于 Python 入口点，请考虑改用 project.scripts。
data：安装在 virtualenv 环境根目录上。

警告：这可能会覆盖现有文件！
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 内的模块目录的名称。

默认模块名称是包名称，其中点和破折号替换为下划线。

包名称需要是有效的 Python 标识符，并且该目录需要包含 __init__.py。例外情况是桩包，其名称以 -stubs 结尾，词干是模块名称，并且包含 __init__.pyi 文件。

对于具有单个模块的命名空间包，路径可以是点分隔的，例如 foo.bar 或 foo-stubs.bar。

对于具有多个模块的命名空间包，路径可以是列表，例如 ["foo", "bar"]。我们建议每个包使用单个模块，将多个包拆分为一个工作区。

请注意，使用此选项会冒着创建两个名称不同但模块名称相同的包的风险。一起安装此类包会导致未指定的行为，通常会导致文件或目录树损坏。

默认值: None

类型: str | list[str]

用法示例:

pyproject.toml

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

`module-root`

常用值是 src（src 布局，默认值）或空路径（平面布局）。

默认值: "src"

类型: str

用法示例:

pyproject.toml

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

`namespace`

构建命名空间包。

构建 PEP 420 隐式命名空间包，允许超过一个根 __init__.py。

当命名空间包包含多个根 __init__.py 时使用此选项，对于具有单个根 __init__.py 的命名空间包，请改用点分隔的 module-name。

要比较点分隔的 module-name 和 namespace = true，下面的第一个示例可以用 module-name = "cloud.database" 表示：有一个根 __init__.py database。在第二个示例中，我们有三个根 (cloud.database、cloud.database_pro、billing.modules.database_pro)，因此需要 namespace = true。

src
└── cloud
    └── database
        ├── __init__.py
        ├── query_builder
        │   └── __init__.py
        └── sql
            ├── parser.py
            └── __init__.py

src
├── cloud
│   ├── database
│   │   ├── __init__.py
│   │   ├── query_builder
│   │   │   └── __init__.py
│   │   └── sql
│   │       ├── __init__.py
│   │       └── parser.py
│   └── database_pro
│       ├── __init__.py
│       └── query_builder.py
└── billing
    └── modules
        └── database_pro
            ├── __init__.py
            └── sql.py

默认值: false

类型: bool

用法示例:

pyproject.toml

[tool.uv.build-backend]
namespace = true

`source-exclude`

要从源分发中排除的文件和目录的 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"]

`工作区`

`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/*"]

配置

`add-bounds`

添加依赖项时的默认版本说明符。

向项目添加依赖项时，如果未提供约束或 URL，则会根据包的最新兼容版本添加约束。默认情况下，使用下限约束，例如 >=1.2.3。

如果提供了 --frozen，则不会执行解析，并且始终会添加没有约束的依赖项。

此选项处于预览状态，可能会在将来的任何版本中更改。

默认值: "lower"

可能的值:

"lower": 仅下限，例如 >=1.2.3
"major": 允许相同的主版本，类似于 semver caret，例如 >=1.2.3, <2.0.0
"minor": 允许相同的次版本，类似于 semver 波浪号，例如 >=1.2.3, <1.3.0
"exact": 锁定确切的版本，例如 ==1.2.3

用法示例:

pyproject.tomluv.toml

[tool.uv]
add-bounds = "major"

add-bounds = "major"

`allow-insecure-host`

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

期望接收主机名（例如 localhost）、主机端口对（例如 localhost:8080）或 URL（例如 https://）。

警告：此列表中包含的主机将不会根据系统的证书存储进行验证。仅在具有已验证来源的安全网络中使用 --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`

为项目缓存构建时要考虑的键。

缓存键使您可以指定在修改时应触发重建的文件或目录。默认情况下，每当修改项目目录中的 pyproject.toml、setup.py 或 setup.cfg 文件，或者添加或删除 src 目录时，uv 都会重建项目，即

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

例如：如果项目使用动态元数据从 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 提交中读取其版本，则可以指定 cache-keys = [{ git = { commit = true }, { file = "pyproject.toml" }] 以在缓存键中包含当前的 Git 提交哈希（除了 pyproject.toml）。还支持通过 cache-keys = [{ git = { commit = true, tags = true } }] 使用 Git 标签。

缓存键还可以包含环境变量。例如，如果项目依赖于 MACOSX_DEPLOYMENT_TARGET 或其他环境变量来确定其行为，则可以指定 cache-keys = [{ env = "MACOSX_DEPLOYMENT_TARGET" }] 以在环境变量更改时使缓存失效。

缓存键仅影响由指定它们的 pyproject.toml 定义的项目（而不是例如影响工作区中的所有成员），并且所有路径和 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 文件编译为字节码。

默认情况下，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 在任何给定时间并发构建的源分发的最大数量。

默认为可用的 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`

项目（直接或传递）依赖项的预定义静态元数据。如果提供，则使解析器能够使用指定的元数据，而不是查询注册表或从源代码构建相关包。

元数据应按照元数据 2.3 标准提供，但仅以下字段有效

name：包的名称。
（可选）version：包的版本。如果省略，则元数据将应用于包的所有版本。
（可选）requires-dist：包的依赖项（例如，werkzeug>=0.14）。
（可选）requires-python：包所需的 Python 版本（例如，>=3.10）。
（可选）provides-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）。需要完整的时间戳以确保解析器在时区中行为一致。

默认值: None

类型: str

用法示例:

pyproject.tomluv.toml

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

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

`extra-index-url`

要使用的包索引的额外 URL，除了 --index-url 之外。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

通过此标志提供的所有索引优先于通过 index_url 或 index 指定的索引，其中 default = true。提供多个索引时，较早的值具有更高的优先级。

要控制存在多个索引时 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`

解析依赖项时要使用的包索引。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

索引按照定义的顺序进行考虑，使得首先定义的索引具有最高优先级。此外，此设置提供的索引比通过 index_url 或 extra_index_url 指定的任何索引具有更高的优先级。uv 将仅考虑包含给定包的第一个索引，除非指定了备用索引策略。

如果索引标记为 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，它将被移动到优先级列表的末尾，以便在解决包时给予最低优先级。此外，将索引标记为默认值将禁用 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`

针对多个索引 URL 进行解析时要使用的策略。

默认情况下，uv 将停止在给定包可用的第一个索引上，并将解决方案限制为该第一个索引上存在的解决方案 (first-index)。这可以防止“依赖项混淆”攻击，攻击者可以在备用索引上以相同的名称上传恶意包。

默认值: "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 包索引的 URL（默认情况下：https://pypi.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

此设置提供的索引的优先级低于通过 extra_index_url 或 index 指定的任何索引。

（已弃用：请改用 index。）

默认值: "https://pypi.ac.cn/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 CLI 来处理身份验证。

默认值: "disabled"

类型: str

用法示例:

pyproject.tomluv.toml

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

keyring-provider = "subprocess"

`link-mode`

从全局缓存安装包时要使用的方法。

默认为 macOS 上的 clone（也称为写入时复制），Linux 和 Windows 上的 hardlink。

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

可能的值:

"clone"：从 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`

不要安装预构建的 wheels。

给定的包将从源代码构建和安装。如果可用，解析器仍将使用预构建的 wheels 提取包元数据。

默认值: false

类型: bool

用法示例:

pyproject.tomluv.toml

[tool.uv]
no-binary = true

no-binary = true

`no-binary-package`

不要安装特定包的预构建 wheels。

默认值: []

类型: list[str]

用法示例:

pyproject.tomluv.toml

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

no-binary-package = ["ruff"]

`no-build`

不要构建源分发。

启用后，解析将不会运行任意 Python 代码。已构建的源分发的缓存 wheels 将被重用，但需要构建分发的操作将退出并显示错误。

默认值: 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`

考虑预发布版本时要使用的策略。

默认情况下，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 软件包索引的 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 安装的镜像 URL。

默认情况下，托管 PyPy 安装是从 downloads.python.org 下载的。可以将此变量设置为镜像 URL，以使用不同的 PyPy 安装源。提供的 URL 将替换为 https://downloads.python.org/pypy，例如，https://downloads.python.org/pypy/pypy3.8-v7.3.7-osx64.tar.bz2。

可以通过使用 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 安装的镜像 URL。

默认情况下，托管 Python 安装是从 python-build-standalone 下载的。可以将此变量设置为镜像 URL，以使用不同的 Python 安装源。提供的 URL 将替换为 https://github.com/astral-sh/python-build-standalone/releases/download，例如，https://github.com/astral-sh/python-build-standalone/releases/download/20240713/cpython-3.12.4%2B20240713-aarch64-apple-darwin-install_only.tar.gz。

可以通过使用 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 安装而不是系统 Python 安装
"system"：优先使用系统 Python 安装而不是托管 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 配置可信发布。

默认情况下，uv 在 GitHub Actions 中运行时会检查可信发布，但如果未配置或工作流程没有足够的权限（例如，来自 fork 的拉取请求），则会忽略它。

默认值: 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`

包含所有可选依赖项。

仅适用于 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`

输出文件中包含的注释的样式，用于指示每个软件包的来源。

默认值: "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) 环境，当安装到由外部软件包管理器（如 apt）管理的 Python 安装中时。应谨慎使用，因为此类 Python 安装明确建议不要被其他软件包管理器（如 uv 或 pip）修改。

默认值: false

类型: bool

用法示例:

pyproject.tomluv.toml

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

[pip]
break-system-packages = true

`compile-bytecode`

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

默认情况下，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`

项目（直接或传递）依赖项的预定义静态元数据。如果提供，则使解析器能够使用指定的元数据，而不是查询注册表或从源代码构建相关包。

元数据应按照元数据 2.3 标准提供，但仅以下字段有效

name：包的名称。
（可选）version：包的版本。如果省略，则元数据将应用于包的所有版本。
（可选）requires-dist：包的依赖项（例如，werkzeug>=0.14）。
（可选）requires-python：包所需的 Python 版本（例如，>=3.10）。
（可选）provides-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.ac.cn/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`

是否发出标记字符串，指示固定依赖项集有效的条件。

即使标记表达式为假，固定依赖项也可能有效，但是当表达式为真时，已知需求是正确的。

默认值: 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 的可选依赖项；可以多次提供。

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

默认值: []

类型: list[str]

用法示例:

pyproject.tomluv.toml

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

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

`extra-index-url`

要使用的包索引的额外 URL，除了 --index-url 之外。

接受符合 PEP 503（简单存储库 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`

在输出文件中包含分发哈希。

默认值: false

类型: bool

用法示例:

pyproject.tomluv.toml

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

[pip]
generate-hashes = true

`group`

包含以下依赖组。

默认值: None

类型: list[str]

用法示例:

pyproject.tomluv.toml

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

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

`index-strategy`

针对多个索引 URL 进行解析时要使用的策略。

默认情况下，uv 将停止在给定包可用的第一个索引上，并将解决方案限制为该第一个索引上存在的解决方案 (first-index)。这可以防止“依赖项混淆”攻击，攻击者可以在备用索引上以相同的名称上传恶意包。

默认值: "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 包索引的 URL（默认情况下：https://pypi.ac.cn/simple）。

接受符合 PEP 503（简单存储库 API）的存储库，或以相同格式布局的本地目录。

此设置提供的索引的优先级低于通过 extra_index_url 指定的任何索引。

默认值: "https://pypi.ac.cn/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 CLI 来处理身份验证。

默认值: disabled

类型: str

用法示例:

pyproject.tomluv.toml

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

[pip]
keyring-provider = "subprocess"

`link-mode`

从全局缓存安装包时要使用的方法。

默认为 macOS 上的 clone（也称为写入时复制），Linux 和 Windows 上的 hardlink。

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

可能的值:

"clone"：从 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`

不要安装预构建的 wheels。

给定的包将从源代码构建和安装。如果可用，解析器仍将使用预构建的 wheels 提取包元数据。

可以提供多个软件包。使用 :all: 禁用所有软件包的二进制文件。使用 :none: 清除先前指定的软件包。

默认值: []

类型: list[str]

用法示例:

pyproject.tomluv.toml

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

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

`no-build`

不要构建源分发。

启用后，解析将不会运行任意 Python 代码。已构建的源分发的缓存 wheels 将被重用，但需要构建分发的操作将退出并显示错误。

--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，则排除指定的可选依赖项。

默认值: []

类型: 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 调用中用作约束文件。

默认值: false

类型: bool

用法示例:

pyproject.tomluv.toml

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

[pip]
no-strip-extras = true

`no-strip-markers`

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

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

默认值: false

类型: bool

用法示例:

pyproject.tomluv.toml

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

[pip]
no-strip-markers = true

`only-binary`

仅使用预构建的轮子；不要构建源分发。

启用后，解析不会运行给定软件包中的代码。将重用已构建源分发的缓存轮子，但是需要构建分发的操作将退出并显示错误。

可以提供多个软件包。使用 :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 和其他顶级文件夹中，就像该位置存在虚拟环境一样。

通常，首选使用 --python 安装到备用环境中，因为通过 --prefix 安装的脚本和其他工件将引用安装解释器，而不是添加到 --prefix 目录的任何解释器，从而使其不可移植。

默认值: None

类型: str

用法示例:

pyproject.tomluv.toml

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

[pip]
prefix = "./prefix"

`prerelease`

考虑预发布版本时要使用的策略。

默认情况下，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 安装到当前工作目录或任何父目录中的虚拟环境中。 --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`

应为其解析需求的平台。

表示为“目标三元组”，这是一个字符串，用于描述目标平台的 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 依赖项。
不支持可编辑安装。
除非本地依赖项指向特定的 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 时，uv 将使用 CUDA 12.6 的 PyTorch 索引。

auto 模式将尝试根据当前安装的 CUDA 驱动程序检测适当的 PyTorch 索引。

此选项处于预览状态，可能会在将来的任何版本中更改。

默认值: null

类型: str

用法示例:

pyproject.tomluv.toml

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

[pip]
torch-backend = "auto"

`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