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

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

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

一、核心特性

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

二、环境初始化

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

生成的标准项目结构:

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

三、pyproject.toml 基础示例

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

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

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

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

四、命令使用方法说明

uv run

  • 用途:运行一个命令或脚本。

  • 使用方法

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

uv init

  • 用途:创建一个新项目。

  • 使用方法

    uv init [OPTIONS] PATH
    
  • 说明:遵循 pyproject.toml 规范。如果目标路径已存在 pyproject.toml 文件,uv 将退出并报错。如果父目录中存在 pyproject.toml,新项目将被添加为工作区成员。

uv add

  • 用途:向项目添加依赖。

  • 使用方法

    uv add [OPTIONS] <PACKAGES|--requirements <REQUIREMENTS>>
    
  • 说明:将依赖添加到项目的 pyproject.toml 文件中。如果依赖已存在,将更新为新版本约束,除非使用了 --frozen 选项。

uv remove

  • 用途:从项目中移除依赖。

  • 使用方法

    uv remove [OPTIONS] <PACKAGES>...
    
  • 说明:从项目的 pyproject.toml 文件中移除依赖。如果依赖不存在,uv 将退出并报错。

uv sync

  • 用途:更新项目的环境。

  • 使用方法

    uv sync [OPTIONS]
    
  • 说明:确保项目环境中的依赖与 uv.lock 文件一致。如果虚拟环境不存在,将创建它。

uv lock

  • 用途:更新项目的锁文件。

  • 使用方法

    uv lock [OPTIONS]
    
  • 说明:如果锁文件不存在,将创建它。如果锁文件已存在,其内容将作为解析的偏好。

uv export

  • 用途:将项目的锁文件导出为其他格式。

  • 使用方法

    uv export [OPTIONS]
    
  • 说明:目前仅支持导出为 requirements.txt 格式。

uv tree

  • 用途:显示项目的依赖树。

  • 使用方法

    uv tree [OPTIONS]
    
  • 说明:显示项目及其依赖的层级结构。

uv tool

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

uv python

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

uv pip

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

uv venv

  • 用途:创建虚拟环境。

  • 使用方法

    uv venv [OPTIONS] [PATH]
    
  • 说明:默认在当前工作目录中创建名为 .venv 的虚拟环境。如果目标路径已存在虚拟环境,将被移除并重新创建。

uv build

  • 用途:构建 Python 包为源分发和轮文件。

  • 使用方法

    uv build [OPTIONS] [SRC]
    
  • 说明:默认从目录构建源分发和轮文件。可以使用 --sdist--wheel 选项分别构建。

uv publish

  • 用途:将分发文件上传到索引。

  • 使用方法

    uv publish [OPTIONS] [FILES]...
    
  • 说明:默认上传 dist 目录中的文件。可以指定文件路径或使用通配符。

uv cache

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

uv self

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

uv version

  • 用途:显示 uv 的版本。

  • 使用方法

    uv version
    

uv generate-shell-completion

  • 用途:生成 shell 补全脚本。

  • 使用方法

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

uv help

  • 用途:显示命令的文档。

  • 使用方法

    uv help [OPTIONS] [COMMAND]...
    

四、pyproject.toml 配置说明

Project metadata

build-constraint-dependencies
  • 类型list[str]

  • 默认值[]

  • 说明:用于限制构建依赖版本的约束。当构建包时,这些约束会限制所选的构建依赖版本。它不会触发包的安装,而是确保在构建过程中满足特定版本要求。

  • 示例

    [tool.uv]
    build-constraint-dependencies = ["setuptools==60.0.0"]
    
conflicts
  • 类型list[list[dict]]

  • 默认值[]

  • 说明:声明冲突的额外依赖或依赖组。当某些额外依赖或依赖组的依赖项相互冲突时,可以通过此配置明确指出,从而避免在安装时出现冲突。

  • 示例

    [tool.uv]
    conflicts = [
        [
            { extra = "extra1" },
            { extra = "extra2" },
        ],
        [
            { group = "group1" },
            { group = "group2" },
        ]
    ]
    
constraint-dependencies
  • 类型list[str]

  • 默认值[]

  • 说明:用于限制项目依赖版本的约束。它不会触发包的安装,而是确保在解析依赖时满足特定版本要求。

  • 示例

    [tool.uv]
    constraint-dependencies = ["grpcio<1.65"]
    
default-groups
  • 类型str | list[str]

  • 默认值["dev"]

  • 说明:指定默认安装的依赖组。可以设置为 "all" 来安装所有组。

  • 示例

    [tool.uv]
    default-groups = ["docs"]
    
dev-dependencies
  • 类型list[str]

  • 默认值[]

  • 说明:项目的开发依赖。这些依赖在 uv runuv sync 中默认安装,但不会出现在项目的发布元数据中。建议使用 dependency-groups.dev 替代此字段。

  • 示例

    [tool.uv]
    dev-dependencies = ["ruff==0.5.0"]
    
environments
  • 类型str | list[str]

  • 默认值[]

  • 说明:指定支持的环境,用于解析依赖。可以通过限制环境来提高性能并避免解析空间中的不可满足分支。

  • 示例

    [tool.uv]
    environments = ["sys_platform == 'darwin'"]
    
index
  • 类型dict

  • 默认值[]

  • 说明:指定解析依赖时使用的索引。可以指定符合 PEP 503 的仓库或本地目录。索引的优先级由定义顺序决定。

  • 示例

    [[tool.uv.index]]
    name = "pytorch"
    url = "https://download.pytorch.org/whl/cu121"
    
managed
  • 类型bool

  • 默认值true

  • 说明:是否由 uv 管理项目。如果设置为 falseuv 在运行时会忽略该项目。

  • 示例

    [tool.uv]
    managed = false
    
override-dependencies
  • 类型list[str]

  • 默认值[]

  • 说明:用于覆盖项目依赖的版本。它会强制选择特定版本的包,无论其他包请求的版本是什么。

  • 示例

    [tool.uv]
    override-dependencies = ["werkzeug==2.3.0"]
    
package
  • 类型bool

  • 默认值true

  • 说明:是否将项目视为 Python 包。如果设置为 false,项目将被视为虚拟项目,不会被构建或安装,仅其依赖项会包含在虚拟环境中。

  • 示例

    [tool.uv]
    package = false
    
required-environments
  • 类型str | list[str]

  • 默认值[]

  • 说明:指定项目必须支持的平台。如果某些包没有源码分发版,此配置可以确保解析出的依赖包含特定平台的 wheel。

  • 示例

    [tool.uv]
    required-environments = [
        "sys_platform == 'darwin' and platform_machine == 'arm64'",
        "sys_platform == 'darwin' and platform_machine == 'x86_64'",
    ]
    
sources
  • 类型dict

  • 默认值{}

  • 说明:用于解析依赖时的额外来源,可以是 Git 仓库、URL、本地路径或替代仓库。

  • 示例

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

    • exclude:排除作为工作区成员的包。
    • members:包含作为工作区成员的包。
  • 类型list[str]

  • 默认值[]

  • 说明:用于定义工作区成员,支持 glob 和显式路径。

  • 示例

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

Configuration

allow-insecure-host
  • 类型list[str]

  • 默认值[]

  • 说明:允许与指定主机进行不安全的连接。可以指定主机名、主机端口对或 URL。警告:使用此选项会绕过 SSL 验证,可能会导致中间人攻击。

  • 示例

    [tool.uv]
    allow-insecure-host = ["localhost:8080"]
    
cache-dir
  • 类型str

  • 默认值None(默认路径为 $XDG_CACHE_HOME/uv$HOME/.cache/uv%LOCALAPPDATA%\uv\cache

  • 说明:指定缓存目录的路径。

  • 示例

    [tool.uv]
    cache-dir = "./.uv_cache"
    
cache-keys
  • 类型list[dict]

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

  • 说明:指定触发项目重建的文件或目录。支持文件、目录、Git 提交信息和环境变量。

  • 示例

    [tool.uv]
    cache-keys = [{ file = "pyproject.toml" }, { file = "requirements.txt" }, { git = { commit = true } }]
    
check-url
  • 类型str

  • 默认值None

  • 说明:在上传前检查索引 URL 中是否已存在相同文件,以避免重复上传。

  • 示例

    [tool.uv]
    check-url = "https://test.pypi.org/simple"
    
compile-bytecode
  • 类型bool

  • 默认值false

  • 说明:在安装后编译 Python 文件为字节码。默认情况下,字节码会在模块首次导入时懒加载编译。

  • 示例

    [tool.uv]
    compile-bytecode = true
    
concurrent-builds
  • 类型int

  • 默认值None(默认为可用 CPU 核心数)

  • 说明:同时构建源分发包的最大数量。

  • 示例

    [tool.uv]
    concurrent-builds = 4
    
concurrent-downloads
  • 类型int

  • 默认值50

  • 说明:同时下载的最大数量。

  • 示例

    [tool.uv]
    concurrent-downloads = 4
    
concurrent-installs
  • 类型int

  • 默认值None(默认为可用 CPU 核心数)

  • 说明:安装和解压包时使用的线程数。

  • 示例

    [tool.uv]
    concurrent-installs = 4
    
config-settings
  • 类型dict

  • 默认值{}

  • 说明:传递给 PEP 517 构建后端的配置设置。

  • 示例

    [tool.uv]
    config-settings = { editable_mode = "compat" }
    
dependency-metadata
  • 类型list[dict]

  • 默认值[]

  • 说明:为依赖项提供预定义的静态元数据。支持 nameversionrequires-distrequires-pythonprovides-extras 字段。

  • 示例

    [tool.uv]
    dependency-metadata = [
        { name = "flask", version = "1.0.0", requires-dist = ["werkzeug"], requires-python = ">=3.6" }
    ]
    
exclude-newer
  • 类型str

  • 默认值None

  • 说明:限制候选包的上传时间,只选择在指定时间之前的包。支持 RFC 3339 时间戳和本地日期。

  • 示例

    [tool.uv]
    exclude-newer = "2006-12-02"
    
extra-index-url
  • 类型list[str]

  • 默认值[]

  • 说明:额外的包索引 URL,优先级高于 index-urlindex 中的默认索引。

  • 示例

    [tool.uv]
    extra-index-url = ["https://download.pytorch.org/whl/cpu"]
    
find-links
  • 类型list[str]

  • 默认值[]

  • 说明:额外的候选分发包位置,可以是本地目录或包含包文件链接的网页。

  • 示例

    [tool.uv]
    find-links = ["https://download.pytorch.org/whl/torch_stable.html"]
    
fork-strategy
  • 类型str

  • 默认值"requires-python"

  • 说明:在不同 Python 版本和平台上选择多个版本的包时的策略。可选值为 "fewest"(选择最少版本)和 "requires-python"(选择最新版本)。

  • 示例

    [tool.uv]
    fork-strategy = "fewest"
    
index
  • 类型dict

  • 默认值[]

  • 说明:指定解析依赖时使用的包索引。支持 PEP 503 兼容的仓库或本地目录。索引的优先级由定义顺序决定。

  • 示例

    [[tool.uv.index]]
    name = "pytorch"
    url = "https://download.pytorch.org/whl/cu121"
    
index-strategy
  • 类型str

  • 默认值"first-index"

  • 说明:在多个索引 URL 中解析时的策略。可选值为 "first-index"(仅使用第一个索引的结果)、"unsafe-first-match""unsafe-best-match"

  • 示例

    [tool.uv]
    index-strategy = "unsafe-best-match"
    
index-url
  • 类型str

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

  • 说明:默认的 Python 包索引 URL。优先级低于 extra-index-urlindex 中的索引。

  • 示例

    [tool.uv]
    index-url = "https://test.pypi.org/simple"
    
keyring-provider
  • 类型str

  • 默认值"disabled"

  • 说明:是否使用 keyring 提供身份验证。目前仅支持 subprocess 模式。

  • 示例

    [tool.uv]
    keyring-provider = "subprocess"
    
link-mode
  • 类型str

  • 默认值"clone"(macOS)或 "hardlink"(Linux 和 Windows)

  • 说明:从全局缓存安装包时使用的方法。可选值为 "clone""copy""hardlink""symlink"

  • 示例

    [tool.uv]
    link-mode = "copy"
    
native-tls
  • 类型bool

  • 默认值false

  • 说明:是否从平台的原生证书库加载 TLS 证书。默认情况下,使用内置的 webpki-roots 证书。

  • 示例

    [tool.uv]
    native-tls = true
    
no-binary
  • 类型bool

  • 默认值false

  • 说明:不安装预构建的 wheel 包,而是从源码构建和安装。

  • 示例

    [tool.uv]
    no-binary = truef"]
    
no-binary-package
  • 类型list[str]

  • 默认值[]

  • 说明:指定某些包不使用预构建的 wheel,而是从源码构建和安装。

  • 示例

    [tool.uv]
    no-binary-package = ["ruff"]
    
no-build
  • 类型bool

  • 默认值false

  • 说明:不构建源分发包。启用后,解析过程不会运行任意 Python 代码,而是直接使用缓存的 wheel。

  • 示例

    [tool.uv]
    no-build = true
    
no-build-isolation
  • 类型bool

  • 默认值false

  • 说明:在构建源分发包时禁用隔离。假设 PEP 518 指定的构建依赖已经安装。

  • 示例

    [tool.uv]
    no-build-isolation = true
    
no-build-isolation-package
  • 类型list[str]

  • 默认值[]

  • 说明:为特定包禁用构建隔离。假设这些包的 PEP 518 构建依赖已经安装。

  • 示例

    [tool.uv]
    no-build-isolation-package = ["package1", "package2"]
    
no-build-package
  • 类型list[str]

  • 默认值[]

  • 说明:不构建特定包的源分发包。

  • 示例

    [tool.uv]
    no-build-package = ["ruff"]
    
no-cache
  • 类型bool

  • 默认值false

  • 说明:不使用缓存,而是使用临时目录进行操作。

  • 示例

    [tool.uv]
    no-cache = true
    
no-index
  • 类型bool

  • 默认值false

  • 说明:忽略所有注册表索引(例如 PyPI),仅依赖于直接 URL 依赖项和通过 --find-links 提供的依赖项。

  • 示例

    [tool.uv]
    no-index = true
    
no-sources
  • 类型bool

  • 默认值false

  • 说明:忽略 tool.uv.sources 表中的依赖来源,仅使用标准的、可发布的包元数据。

  • 示例

    [tool.uv]
    no-sources = true
    
offline
  • 类型bool

  • 默认值false

  • 说明:禁用网络访问,仅依赖于本地缓存数据和本地文件。

  • 示例

    [tool.uv]
    offline = true
    
prerelease
  • 类型str

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

  • 说明:预发布版本的策略。可选值包括:

    • "disallow":禁止所有预发布版本
    • "allow":允许所有预发布版本
    • "if-necessary":如果包的所有版本都是预发布版本,则允许
    • "explicit":仅允许显式标记为预发布的包
    • "if-necessary-or-explicit":如果包的所有版本都是预发布版本,或者包的版本要求中显式标记为预发布,则允许
  • 示例

    [tool.uv]
    prerelease = "allow"
    
preview
  • 类型bool

  • 默认值false

  • 说明:是否启用实验性功能。

  • 示例

    [tool.uv]
    preview = true
    
publish-url
  • 类型str

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

  • 说明:发布包到 Python 包索引的 URL。

  • 示例

    [tool.uv]
    publish-url = "https://test.pypi.org/legacy/"
    
pypy-install-mirror
  • 类型str

  • 默认值None

  • 说明:用于下载 PyPy 安装的镜像 URL。默认情况下,从 downloads.python.org 下载。

  • 示例

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

  • 默认值"automatic"

  • 说明:是否允许下载 Python。可选值包括:

    • "automatic":自动下载所需的 Python 安装
    • "manual":需要手动安装 Python
    • "never":禁止下载 Python
  • 示例

    [tool.uv]
    python-downloads = "manual"
    
python-install-mirror
  • 类型str

  • 默认值None

  • 说明:用于下载 Python 安装的镜像 URL。默认情况下,从 python-build-standalone 下载。

  • 示例

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

  • 默认值"managed"

  • 说明:是否优先使用已安装的系统 Python,还是由 uv 下载和安装的 Python。可选值包括:

    • "only-managed":仅使用由 uv 管理的 Python 安装
    • "managed":优先使用由 uv 管理的 Python 安装
    • "system":优先使用系统 Python 安装
    • "only-system":仅使用系统 Python 安装
  • 示例

    [tool.uv]
    python-preference = "managed"
    
reinstall
  • 类型bool

  • 默认值false

  • 说明:重新安装所有包,无论它们是否已经安装。此选项会隐式启用 refresh

  • 示例

    [tool.uv]
    reinstall = true
    
reinstall-package
  • 类型list[str]

  • 默认值[]

  • 说明:重新安装特定包,无论它们是否已经安装。此选项会隐式启用 refresh-package

  • 示例

    [tool.uv]
    reinstall-package = ["ruff"]
    
required-version
  • 类型str

  • 默认值null

  • 说明:强制 uv 的版本要求。如果运行时 uv 的版本不符合要求,将退出并报错。

  • 示例

    [tool.uv]
    required-version = ">=0.5.0"
    
resolution
  • 类型str

  • 默认值"highest"

  • 说明:解析依赖时选择兼容版本的策略。可选值包括:

    • "highest":选择最高兼容版本
    • "lowest":选择最低兼容版本
    • "lowest-direct":直接依赖选择最低兼容版本,间接依赖选择最高兼容版本
  • 示例

    [tool.uv]
    resolution = "lowest-direct"
    
trusted-publishing
  • 类型str

  • 默认值"automatic"

  • 说明:在 GitHub Actions 中配置可信发布。默认情况下,uv 会在 GitHub Actions 中检查可信发布。

  • 示例

    [tool.uv]
    trusted-publishing = "always"
    
upgrade
  • 类型bool

  • 默认值false

  • 说明:是否允许升级包,忽略现有输出文件中的固定版本。

  • 示例

    [tool.uv]
    upgrade = true
    
upgrade-package
  • 类型list[str]

  • 默认值[]

  • 说明:允许升级特定包,忽略现有输出文件中的固定版本。可以指定包名或版本范围。

  • 示例

    [tool.uv]
    upgrade-package = ["ruff<0.5.0"]
    
pip
  • 类型dict
  • 默认值{}(具体配置项见下文)
  • 说明uv pip 命令行界面的特定设置。这些设置仅在 uv pip 命令中生效。
all-extras
  • 类型bool

  • 默认值false

  • 说明:是否包含所有可选依赖项。仅适用于 pyproject.tomlsetup.pysetup.cfg 源。

  • 示例

    [tool.uv.pip]
    all-extras = true
    
allow-empty-requirements
  • 类型bool

  • 默认值false

  • 说明:是否允许 uv pip sync 使用空的依赖项,这将清除环境中的所有包。

  • 示例

    [tool.uv.pip]
    allow-empty-requirements = true
    
annotation-style
  • 类型str

  • 默认值"split"

  • 说明:在输出文件中注释的样式。可选值为 "line"(单行注释)和 "split"(每行一个注释)。

  • 示例

    [tool.uv.pip]
    annotation-style = "line"
    
break-system-packages
  • 类型bool

  • 默认值false

  • 说明:是否允许修改 EXTERNALLY-MANAGED 的 Python 安装。仅在 CI 环境中推荐使用。

  • 示例

    [tool.uv.pip]
    break-system-packages = true
    
compile-bytecode
  • 类型bool

  • 默认值false

  • 说明:是否在安装后编译 Python 文件为字节码。默认情况下,字节码会在模块首次导入时懒加载编译。

  • 示例

    [tool.uv.pip]
    compile-bytecode = true
    
config-settings
  • 类型dict

  • 默认值{}

  • 说明:传递给 PEP 517 构建后端的配置设置。

  • 示例

    [tool.uv.pip]
    config-settings = { editable_mode = "compat" }
    
custom-compile-command
  • 类型str

  • 默认值None

  • 说明:在 uv pip compile 生成的输出文件顶部添加的自定义编译命令。

  • 示例

    [tool.uv.pip]
    custom-compile-command = "./custom-uv-compile.sh"
    
dependency-metadata
  • 类型list[dict]

  • 默认值[]

  • 说明:为依赖项提供预定义的静态元数据。

  • 示例

    [tool.uv.pip]
    dependency-metadata = [
        { name = "flask", version = "1.0.0", requires-dist = ["werkzeug"], requires-python = ">=3.6" }
    ]
    
emit-build-options**
  • 类型bool
  • 默认值false
  • 说明:是否在 uv pip compile 生成的输出文件中包含 --no-binary--only-binary 选项。
  • 示例
[tool.uv.pip]
emit-build-options = true
emit-find-links
  • 类型bool

  • 默认值false

  • 说明:是否在 uv pip compile 生成的输出文件中包含 --find-links 选项。

  • 示例

    [tool.uv.pip]
    emit-find-links = true
    
emit-index-annotation
  • 类型bool

  • 默认值false

  • 说明:是否在 uv pip compile 生成的输出文件中包含索引注释。

  • 示例

    [tool.uv.pip]
    emit-index-annotation = true
    
emit-index-url
  • 类型bool

  • 默认值false

  • 说明:是否在 uv pip compile 生成的输出文件中包含 --index-url--extra-index-url 选项。

  • 示例

    [tool.uv.pip]
    emit-index-url = true
    
emit-marker-expression
  • 类型bool

  • 默认值false

  • 说明:是否在输出文件中包含标记表达式,指示依赖项有效的条件。

  • 示例

    [tool.uv.pip]
    emit-marker-expression = true
    
exclude-newer
  • 类型str

  • 默认值None

  • 说明:限制候选包的上传时间,仅选择在指定时间之前的包。

  • 示例

    [tool.uv.pip]
    exclude-newer = "2006-12-02T02:07:43Z"
    
extra
  • 类型list[str]

  • 默认值[]

  • 说明:包含的可选依赖项。仅适用于 pyproject.tomlsetup.pysetup.cfg 源。

  • 示例

    [tool.uv.pip]
    extra = ["dev", "docs"]
    
extra-index-url
  • 类型list[str]

  • 默认值[]

  • 说明:额外的包索引 URL,优先级高于 index-url

  • 示例

    [tool.uv.pip]
    extra-index-url = ["https://download.pytorch.org/whl/cpu"]
    
find-links
  • 类型list[str]

  • 默认值[]

  • 说明:额外的候选分发包位置,可以是本地目录或包含包文件链接的网页。

  • 示例

    [tool.uv.pip]
    find-links = ["https://download.pytorch.org/whl/torch_stable.html"]
    
fork-strategy
  • 类型str

  • 默认值"requires-python"

  • 说明:在不同 Python 版本和平台上选择多个版本的包时的策略。

  • 示例

    [tool.uv.pip]
    fork-strategy = "fewest"
    
generate-hashes
  • 类型bool

  • 默认值false

  • 说明:是否在输出文件中包含分发包的哈希值。

  • 示例

    [tool.uv.pip]
    generate-hashes = true
    
group
  • 类型list[str]

  • 默认值None

  • 说明:指定要包含的依赖组。

  • 示例

    [tool.uv.pip]
    group = ["dev", "docs"]
    
index-strategy
  • 类型str

  • 默认值"first-index"

  • 说明:在多个索引 URL 中解析时的策略。可选值为:

    • "first-index":仅使用第一个索引的结果。
    • "unsafe-first-match":在所有索引中搜索每个包名,优先使用第一个索引中的版本。
    • "unsafe-best-match":在所有索引中搜索每个包名,选择最佳版本。
  • 示例

    [tool.uv.pip]
    index-strategy = "unsafe-best-match"
    
index-url
  • 类型str

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

  • 说明:Python 包索引的 URL。此设置的优先级低于 extra-index-url

  • 示例

    [tool.uv.pip]
    index-url = "https://test.pypi.org/simple"
    
keyring-provider
  • 类型str

  • 默认值"disabled"

  • 说明:是否使用 keyring 提供身份验证。目前仅支持 subprocess 模式。

  • 示例

    [tool.uv.pip]
    keyring-provider = "subprocess"
    
link-mode
  • 类型str

  • 默认值"clone"(macOS)或 "hardlink"(Linux 和 Windows)

  • 说明:从全局缓存安装包时使用的方法。可选值为:

    • "clone":使用 Copy-on-Write 模式。
    • "copy":复制包。
    • "hardlink":创建硬链接。
    • "symlink":创建符号链接。
  • 示例

    [tool.uv.pip]
    link-mode = "copy"
    
no-annotate
  • 类型bool

  • 默认值false

  • 说明:是否在 uv pip compile 生成的输出文件中排除注释。

  • 示例

    [tool.uv.pip]
    no-annotate = true
    
no-binary
  • 类型list[str]

  • 默认值[]

  • 说明:指定不使用预构建的 wheel 包,而是从源码构建和安装。可以指定包名或 :all:(禁用所有包的二进制安装)。

  • 示例

    [tool.uv.pip]
    no-binary = ["ruff"]
    
no-build
  • 类型bool

  • 默认值false

  • 说明:是否禁用源分发包的构建。启用后,解析过程不会运行任意 Python 代码。

  • 示例

    [tool.uv.pip]
    no-build = true
    
no-build-isolation
  • 类型bool

  • 默认值false

  • 说明:是否禁用构建源分发包时的隔离。假设 PEP 518 指定的构建依赖已经安装。

  • 示例

    [tool.uv.pip]
    no-build-isolation = true
    
no-build-isolation-package
  • 类型list[str]

  • 默认值[]

  • 说明:为特定包禁用构建隔离。假设这些包的 PEP 518 构建依赖已经安装。

  • 示例

    [tool.uv.pip]
    no-build-isolation-package = ["package1", "package2"]
    
no-deps
  • 类型bool

  • 默认值false

  • 说明:是否忽略包的依赖项,仅添加显式列出的包到结果依赖文件中。

  • 示例

    [tool.uv.pip]
    no-deps = true
    
no-emit-package
  • 类型list[str]

  • 默认值[]

  • 说明:指定要从输出解析中省略的包。其依赖项仍将包含在解析中。

  • 示例

    [tool.uv.pip]
    no-emit-package = ["ruff"]
    
no-extra
  • 类型list[str]

  • 默认值[]

  • 说明:如果启用了 all-extras,则排除指定的可选依赖项。

  • 示例

    [tool.uv.pip]
    all-extras = true
    no-extra = ["dev", "docs"]
    
no-header
  • 类型bool

  • 默认值false

  • 说明:是否排除 uv pip compile 生成的输出文件顶部的注释头。

  • 示例

    [tool.uv.pip]
    no-header = true
    
no-index
  • 类型bool

  • 默认值false

  • 说明:是否忽略所有注册表索引(例如 PyPI),仅依赖于直接 URL 依赖项和通过 --find-links 提供的依赖项。

  • 示例

    [tool.uv.pip]
    no-index = true
    
no-sources
  • 类型bool

  • 默认值false

  • 说明:是否忽略 tool.uv.sources 表中的依赖来源,仅使用标准的、可发布的包元数据。

  • 示例

    [tool.uv.pip]
    no-sources = true
    
no-strip-extras
  • 类型bool

  • 默认值false

  • 说明:是否在输出文件中保留可选依赖项。默认情况下,可选依赖项会被移除。

  • 示例

    [tool.uv.pip]
    no-strip-extras = true
    
no-strip-markers
  • 类型bool

  • 默认值false

  • 说明:是否在输出文件中保留环境标记。默认情况下,环境标记会被移除。

  • 示例

    [tool.uv.pip]
    no-strip-markers = true
    
only-binary
  • 类型list[str]

  • 默认值[]

  • 说明:仅使用预构建的 wheel 包,不从源码构建。可以指定包名或 :all:(仅使用所有包的二进制安装)。

  • 示例

    [tool.uv.pip]
    only-binary = ["ruff"]
    
output-file
  • 类型str

  • 默认值None

  • 说明:指定 uv pip compile 生成的依赖文件的输出路径。如果文件已存在,将优先使用现有版本进行解析,除非同时指定了 --upgrade

  • 示例

    [tool.uv.pip]
    output-file = "requirements.txt"
    
prefix
  • 类型str

  • 默认值None

  • 说明:指定安装包的目标目录,类似于虚拟环境的结构。不推荐使用,因为安装的脚本将引用安装解释器,而不是目标目录中的解释器。

  • 示例

    [tool.uv.pip]
    prefix = "./prefix"
    
prerelease
  • 类型str

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

  • 说明:预发布版本的策略。可选值包括:

    • "disallow":禁止所有预发布版本。
    • "allow":允许所有预发布版本。
    • "if-necessary":如果包的所有版本都是预发布版本,则允许。
    • "explicit":仅允许显式标记为预发布的包。
    • "if-necessary-or-explicit":如果包的所有版本都是预发布版本,或者包的版本要求中显式标记为预发布,则允许。
  • 示例

    [tool.uv.pip]
    prerelease = "allow"
    
python
  • 类型str

  • 默认值None

  • 说明:指定安装包的目标 Python 解释器。支持以下格式:

    • 3.10:查找已安装的 Python 3.10(Windows 上的注册表或 Linux/macOS 上的 python3.10)。
    • python3.10python.exe:在 PATH 中查找指定名称的二进制文件。
    • /home/ferris/.local/bin/python3.10:使用指定路径的 Python。
  • 示例

    [tool.uv.pip]
    python = "3.10"
    
python-platform
  • 类型str

  • 默认值None

  • 说明:指定解析依赖的目标平台,格式为“目标三元组”,例如 x86_64-unknown-linux-gnuaarch64-apple-darwin

  • 示例

    [tool.uv.pip]
    python-platform = "x86_64-unknown-linux-gnu"
    
python-version
  • 类型str

  • 默认值None

  • 说明:指定解析依赖时支持的最低 Python 版本,例如 3.83.8.17。如果省略补丁版本,则假定为最低补丁版本,例如 3.8 表示 3.8.0

  • 示例

    [tool.uv.pip]
    python-version = "3.8"
    
reinstall
  • 类型bool

  • 默认值false

  • 说明:是否重新安装所有包,无论它们是否已经安装。此选项隐式启用 refresh

  • 示例

    [tool.uv.pip]
    reinstall = true
    
reinstall-package
  • 类型list[str]

  • 默认值[]

  • 说明:重新安装特定包,无论它们是否已经安装。此选项隐式启用 refresh-package

  • 示例

    [tool.uv.pip]
    reinstall-package = ["ruff"]
    
require-hashes
  • 类型bool

  • 默认值false

  • 说明:是否要求每个依赖项都提供匹配的哈希值。启用后,所有依赖项都必须提供哈希值,并且必须是固定版本(例如 ==1.0.0)或通过直接 URL 指定。

  • 示例

    [tool.uv.pip]
    require-hashes = true
    
resolution
  • 类型str

  • 默认值"highest"

  • 说明:解析依赖时选择兼容版本的策略。可选值包括:

    • "highest":选择最高兼容版本。
    • "lowest":选择最低兼容版本。
    • "lowest-direct":直接依赖选择最低兼容版本,间接依赖选择最高兼容版本。
  • 示例

    [tool.uv.pip]
    resolution = "lowest-direct"
    
strict
  • 类型bool

  • 默认值false

  • 说明:是否验证 Python 环境,检测缺少依赖项和其他问题。

  • 示例

    [tool.uv.pip]
    strict = true
    
system
  • 类型bool

  • 默认值false

  • 说明:是否将包安装到系统 Python 环境中。默认情况下,uv 会安装到当前工作目录或父目录中的虚拟环境中。

  • 示例

    [tool.uv.pip]
    system = true
    
target
  • 类型str

  • 默认值None

  • 说明:指定将包安装到的目标目录,而不是安装到虚拟环境或系统 Python 环境中。包将安装到目录的顶层。

  • 示例

    [tool.uv.pip]
    target = "./target"
    
torch-backend
  • 类型str

  • 默认值null

  • 说明:指定 PyTorch 生态系统中使用的后端。可选值包括:

    • cpu:使用 CPU-only 的 PyTorch 索引。
    • cu126:使用 CUDA 12.6 的 PyTorch 索引。
    • auto:自动检测当前安装的 CUDA 驱动程序并选择合适的 PyTorch 索引。
  • 示例

    [tool.uv.pip]
    torch-backend = "auto"
    
universal
  • 类型bool

  • 默认值false

  • 说明:是否执行通用解析,尝试生成一个兼容所有操作系统、架构和 Python 实现的单一 requirements.txt 文件。在通用模式下,当前 Python 版本(或用户指定的 --python-version)将被视为下限。

  • 示例

    [tool.uv.pip]
    universal = true
    
upgrade
  • 类型bool

  • 默认值false

  • 说明:是否允许升级包,忽略现有输出文件中的固定版本。

  • 示例

    [tool.uv.pip]
    upgrade = true
    
upgrade-package
  • 类型list[str]

  • 默认值[]

  • 说明:允许升级特定包,忽略现有输出文件中的固定版本。可以指定包名或版本范围。

  • 示例

    [tool.uv.pip]
    upgrade-package = ["ruff<0.5.0"]
    
verify-hashes
  • 类型bool

  • 默认值true

  • 说明:是否验证要求文件中提供的哈希值。与 require-hashes 不同,此选项不会要求所有依赖项都提供哈希值,而是仅验证那些提供了哈希值的依赖项。

  • 示例

    [tool.uv.pip]
    verify-hashes = true
    
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

船长@Quant

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付:¥1
获取中
扫码支付

您的余额不足,请更换扫码支付或充值

打赏作者

实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值