设置

项目元数据

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

`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操作时会解析所有可能的环境。但您可以限制支持的环境集合以提高性能，并避免解决方案空间中不可满足的分支。

当使用uv pip compile命令并带有--universal标志时，这些环境设置同样会被遵循。

默认值: []

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

在解析项目依赖时应用的覆盖规则。

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

虽然约束条件是叠加式的（即与组成包的要求相结合），但覆盖规则是绝对式的（即完全取代任何组成包的要求）。

将某个包包含为覆盖项不会自动触发该包的安装；相反，该项目必须在其第一方或传递依赖项的其他地方请求该包。

注意

在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的wheel文件，那么它将无法在macOS或Windows系统上安装。

默认情况下，uv要求每个包至少包含一个与指定Python版本兼容的wheel文件。通过required-environments设置可以确保最终解析结果包含针对特定平台的wheel文件，如果找不到符合条件的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]
# 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、本地路径或替代注册表。

更多详情请参见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）。

注意

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

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

所有接受通配符的选项都使用来自PEP 639的可移植通配符模式。

Each entry is a directory, whose contents are copied to the matching directory in the wheel in -.data/(purelib|platlib|headers|scripts|data). Upon installation, this data is moved to its target location, as defined by https://docs.python.org/3.12/library/sysconfig.html#installation-paths. Usually, small data files are included by placing them in the Python module instead of using data includes.

scripts: 安装到可执行文件目录，在Unix上是/bin或在Windows上是\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`

Glob表达式，用于指定要从源代码分发中排除的文件和目录。

默认值: []

类型: list[str]

使用示例:

pyproject.toml

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

`source-include`

全局表达式，用于指定在源代码分发中额外包含哪些文件和目录。

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

默认值: []

类型: list[str]

使用示例:

pyproject.toml

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

`wheel-exclude`

全局表达式，用于指定要从wheel中排除的文件和目录。

默认值: []

类型: list[str]

使用示例:

pyproject.toml

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

`workspace`

`exclude`

要排除作为工作空间成员的包。如果一个包同时匹配members和exclude，它将被排除。

支持通配符和显式路径。

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

默认值: []

类型: list[str]

使用示例:

pyproject.toml

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

`members`

包含作为工作区成员的软件包。

支持通配符和显式路径两种方式。

有关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验证，可能使您遭受中间人攻击。

默认值: []

类型: list[str]

使用示例:

pyproject.tomluv.toml

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

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

`cache-dir`

缓存目录的路径。

默认为 $XDG_CACHE_HOME/uv 或 Linux 和 macOS 上的 $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之外）都会重新构建项目。

支持使用通配符（Globs），遵循glob包的语法规则。例如，若需在项目目录或其任意子目录中的.toml文件被修改时使缓存失效，可指定cache-keys = [{ file = "**/*.toml" }]。请注意，使用通配符可能消耗较多资源，因为uv可能需要遍历文件系统来确定是否有文件发生变更。

缓存键(cache keys)也可以包含版本控制信息。例如，如果项目使用 setuptools_scm从Git提交中读取版本号，您可以指定cache-keys = [{ git = { commit = true }, { file = "pyproject.toml" }] 将当前Git提交哈希包含在缓存键中(除了 pyproject.toml文件外)。Git标签也支持通过cache-keys = [{ git = { commit = true, tags = true } }]方式包含。

缓存键也可以包含环境变量。例如，如果一个项目依赖 MACOSX_DEPLOYMENT_TARGET或其他环境变量来决定其行为，你可以指定cache-keys = [{ env = "MACOSX_DEPLOYMENT_TARGET" }]来使缓存失效，当环境变量发生变化时。

缓存键仅影响由pyproject.toml定义的项目（而不是影响工作区中的所有成员），并且所有路径和通配符都被解释为相对于项目目录。

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

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

元数据应按照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）和本地日期格式（例如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之外，额外使用的包索引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.org/simple）。

接受符合PEP 503规范的代码仓库（简单仓库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（也称为写时复制），在 Linux 和 Windows 上使用 hardlink。

默认值: "clone" (macOS) 或 "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`

不要安装预构建的轮子。

给定的软件包将从源代码构建并安装。解析器仍会使用预构建的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`

不要构建源代码发行版。

启用后，解析过程将不会执行任意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`

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

默认情况下，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下载并安装的版本。

默认值: "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配置可信发布。

By default, uv checks for trusted publishing when running in GitHub Actions, but ignores it if it isn't configured or the workflow doesn't have enough permissions (e.g., a pull request from a 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`

允许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`

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

元数据应按照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.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`

是否发出一个标记字符串，用于指示固定依赖集合有效的条件。

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

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

包含指定额外项的可选依赖项；可以多次提供。

仅适用于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之外，额外使用的包索引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.org/simple）。

接受符合PEP 503规范的代码仓库（简单仓库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（也称为写时复制），在 Linux 和 Windows 上使用 hardlink。

默认值: "clone" (macOS) 或 "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`

不要安装预构建的轮子。

给定的软件包将从源代码构建并安装。解析器仍会使用预构建的wheel文件来提取软件包元数据（如果可用）。

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

默认值: []

类型: list[str]

使用示例:

pyproject.tomluv.toml

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

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

`no-build`

不要构建源代码发行版。

启用后，解析过程将不会执行任意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`

忽略包依赖关系，仅将命令行中明确列出的包添加到最终的需求文件中。

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

在输出文件中包含额外内容。

默认情况下，uv会剥离额外依赖项，因为由额外依赖项引入的任何包都已直接作为依赖项包含在输出文件中。此外，使用--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`

仅使用预构建的wheel包；不要构建源代码分发版。

启用后，解析过程将不会运行来自指定包的代码。已构建的源代码发行版的缓存wheel将被重用，但需要构建发行版的操作将以错误退出。

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

默认值: []

类型: list[str]

使用示例:

pyproject.tomluv.toml

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

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

`output-file`

将uv pip compile生成的需求写入指定的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`

验证需求文件中提供的任何哈希值。

与--require-hashes不同，--verify-hashes并不要求所有依赖项都必须包含哈希值；相反，它只会对那些确实包含哈希值的依赖项进行验证。

默认值: true

类型: bool

使用示例:

pyproject.tomluv.toml

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

[pip]
verify-hashes = true