UV使用指南:比 pip 快 10-100 倍的Python项目包管理工具,内附全部命令和配置参数说明
UV 是由 Astral 团队开发的一款用 Rust 编写的 Python 包和项目管理器,目标是成为“Python 的 “Cargo”。它集成了 pip、pip-tools、pipx、poetry、pyenv、twine 和 virtualenv 等工具的功能。
一、核心特性
- 多工具集成:替代
pip
/pip-tools
/virtualenv
/poetry
等工具链 - 兼容性强:支持
pyproject.toml
、requirements.txt
,兼容现有 Python 生态工具链。 - 极速安装:Rust 实现比
pip
快 ‼️10-100‼️ 倍。🚀🚀🚀 - 确定性构建:通过
uv.lock
文件保证跨环境一致性 - 跨平台支持:完整支持 Linux/macOS/Windows
二、环境初始化
# 创建新项目
mkdir my_project && cd my_project
uv venv # 创建虚拟环境
uv init # 生成标准项目结构
生成的标准项目结构:
.
├── .venv
│ ├── bin
│ ├── lib
│ ├── share
│ ├── .gitignore
│ ├── CACHEDIR.TAG
│ └── pyvenv.cfg
├── .gitignore
├── .python-version
├── README.md
├── main.py
├── pyproject.toml
└── uv.lock
三、pyproject.toml
基础示例
[project]
name = "my-project"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.10"
authors = [{ name = "name", email = "email@example.com" }]
# 主依赖声明
dependencies = ["matplotlib>=3.10.1", "numpy>=2.2.5", "pandas>=2.2.3"]
# 可选依赖
[dependency-groups]
dev = ["black>=25.1.0", "pytest>=8.3.5"]
ml = [
"scikit-learn>=1.6.1",
"torch>=2.6.0",
"torchaudio>=2.6.0",
"torchvision>=0.21.0",
]
# UV 扩展配置
[[tool.uv.index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple" # 镜像源
proxy = "http://127.0.0.1:1080" # 网络代理
default = true
四、命令使用方法说明
uv run
-
用途:运行一个命令或脚本。
-
使用方法:
uv run [OPTIONS] [COMMAND]
-
说明:确保命令在 Python 环境中运行。如果命令是一个以
.py
结尾的文件或 HTTP(S) 链接,文件将被当作脚本运行。如果命令包含内联依赖元数据,这些依赖将被安装到一个临时环境中。
uv init
-
用途:创建一个新项目。
-
使用方法:
uv init [OPTIONS] PATH
-
说明:遵循
pyproject.toml
规范。如果目标路径已存在pyproject.toml
文件,uv
将退出并报错。如果父目录中存在pyproject.toml
,新项目将被添加为工作区成员。
uv add
-
用途:向项目添加依赖。
-
使用方法:
uv add [OPTIONS] <PACKAGES|--requirements <REQUIREMENTS>>
-
说明:将依赖添加到项目的
pyproject.toml
文件中。如果依赖已存在,将更新为新版本约束,除非使用了--frozen
选项。
uv remove
-
用途:从项目中移除依赖。
-
使用方法:
uv remove [OPTIONS] <PACKAGES>...
-
说明:从项目的
pyproject.toml
文件中移除依赖。如果依赖不存在,uv
将退出并报错。
uv sync
-
用途:更新项目的环境。
-
使用方法:
uv sync [OPTIONS]
-
说明:确保项目环境中的依赖与
uv.lock
文件一致。如果虚拟环境不存在,将创建它。
uv lock
-
用途:更新项目的锁文件。
-
使用方法:
uv lock [OPTIONS]
-
说明:如果锁文件不存在,将创建它。如果锁文件已存在,其内容将作为解析的偏好。
uv export
-
用途:将项目的锁文件导出为其他格式。
-
使用方法:
uv export [OPTIONS]
-
说明:目前仅支持导出为
requirements.txt
格式。
uv tree
-
用途:显示项目的依赖树。
-
使用方法:
uv tree [OPTIONS]
-
说明:显示项目及其依赖的层级结构。
uv tool
- 用途:运行和安装由 Python 包提供的命令。
- 子命令:
uv tool run
:运行一个由 Python 包提供的命令。uv tool install
:安装工具。uv tool upgrade
:升级已安装的工具。uv tool list
:列出已安装的工具。uv tool uninstall
:卸载工具。uv tool update-shell
:确保工具可执行目录在PATH
中。uv tool dir
:显示工具目录的路径。
uv python
- 用途:管理 Python 版本和安装。
- 子命令:
uv python list
:列出可用的 Python 安装。uv python install
:下载并安装 Python 版本。uv python find
:搜索 Python 安装。uv python pin
:固定到特定的 Python 版本。uv python dir
:显示uv
的 Python 安装目录。uv python uninstall
:卸载 Python 版本。
uv pip
- 用途:以 pip 兼容的接口管理 Python 包。
- 子命令:
uv pip compile
:编译requirements.in
文件为requirements.txt
文件。uv pip sync
:同步环境与requirements.txt
文件。uv pip install
:安装包到环境中。uv pip uninstall
:从环境中卸载包。uv pip freeze
:以要求格式列出环境中安装的包。uv pip list
:以表格格式列出环境中安装的包。uv pip show
:显示一个或多个已安装包的信息。uv pip tree
:显示环境的依赖树。uv pip check
:验证已安装包的依赖是否兼容。
uv venv
-
用途:创建虚拟环境。
-
使用方法:
uv venv [OPTIONS] [PATH]
-
说明:默认在当前工作目录中创建名为
.venv
的虚拟环境。如果目标路径已存在虚拟环境,将被移除并重新创建。
uv build
-
用途:构建 Python 包为源分发和轮文件。
-
使用方法:
uv build [OPTIONS] [SRC]
-
说明:默认从目录构建源分发和轮文件。可以使用
--sdist
和--wheel
选项分别构建。
uv publish
-
用途:将分发文件上传到索引。
-
使用方法:
uv publish [OPTIONS] [FILES]...
-
说明:默认上传
dist
目录中的文件。可以指定文件路径或使用通配符。
uv cache
- 用途:管理
uv
的缓存。 - 子命令:
uv cache clean
:清除缓存。uv cache prune
:修剪缓存中不可达的对象。uv cache dir
:显示缓存目录。
uv self
- 用途:管理
uv
可执行文件。 - 子命令:
uv self update
:更新uv
。
uv version
-
用途:显示
uv
的版本。 -
使用方法:
uv version
uv generate-shell-completion
-
用途:生成 shell 补全脚本。
-
使用方法:
uv generate-shell-completion [OPTIONS] <SHELL>
uv help
-
用途:显示命令的文档。
-
使用方法:
uv help [OPTIONS] [COMMAND]...
四、pyproject.toml
配置说明
Project metadata
build-constraint-dependencies
-
类型:
list[str]
-
默认值:
[]
-
说明:用于限制构建依赖版本的约束。当构建包时,这些约束会限制所选的构建依赖版本。它不会触发包的安装,而是确保在构建过程中满足特定版本要求。
-
示例:
[tool.uv] build-constraint-dependencies = ["setuptools==60.0.0"]
conflicts
-
类型:
list[list[dict]]
-
默认值:
[]
-
说明:声明冲突的额外依赖或依赖组。当某些额外依赖或依赖组的依赖项相互冲突时,可以通过此配置明确指出,从而避免在安装时出现冲突。
-
示例:
[tool.uv] conflicts = [ [ { extra = "extra1" }, { extra = "extra2" }, ], [ { group = "group1" }, { group = "group2" }, ] ]
constraint-dependencies
-
类型:
list[str]
-
默认值:
[]
-
说明:用于限制项目依赖版本的约束。它不会触发包的安装,而是确保在解析依赖时满足特定版本要求。
-
示例:
[tool.uv] constraint-dependencies = ["grpcio<1.65"]
default-groups
-
类型:
str | list[str]
-
默认值:
["dev"]
-
说明:指定默认安装的依赖组。可以设置为
"all"
来安装所有组。 -
示例:
[tool.uv] default-groups = ["docs"]
dev-dependencies
-
类型:
list[str]
-
默认值:
[]
-
说明:项目的开发依赖。这些依赖在
uv run
和uv sync
中默认安装,但不会出现在项目的发布元数据中。建议使用dependency-groups.dev
替代此字段。 -
示例:
[tool.uv] dev-dependencies = ["ruff==0.5.0"]
environments
-
类型:
str | list[str]
-
默认值:
[]
-
说明:指定支持的环境,用于解析依赖。可以通过限制环境来提高性能并避免解析空间中的不可满足分支。
-
示例:
[tool.uv] environments = ["sys_platform == 'darwin'"]
index
-
类型:
dict
-
默认值:
[]
-
说明:指定解析依赖时使用的索引。可以指定符合 PEP 503 的仓库或本地目录。索引的优先级由定义顺序决定。
-
示例:
[[tool.uv.index]] name = "pytorch" url = "https://download.pytorch.org/whl/cu121"
managed
-
类型:
bool
-
默认值:
true
-
说明:是否由
uv
管理项目。如果设置为false
,uv
在运行时会忽略该项目。 -
示例:
[tool.uv] managed = false
override-dependencies
-
类型:
list[str]
-
默认值:
[]
-
说明:用于覆盖项目依赖的版本。它会强制选择特定版本的包,无论其他包请求的版本是什么。
-
示例:
[tool.uv] override-dependencies = ["werkzeug==2.3.0"]
package
-
类型:
bool
-
默认值:
true
-
说明:是否将项目视为 Python 包。如果设置为
false
,项目将被视为虚拟项目,不会被构建或安装,仅其依赖项会包含在虚拟环境中。 -
示例:
[tool.uv] package = false
required-environments
-
类型:
str | list[str]
-
默认值:
[]
-
说明:指定项目必须支持的平台。如果某些包没有源码分发版,此配置可以确保解析出的依赖包含特定平台的 wheel。
-
示例:
[tool.uv] required-environments = [ "sys_platform == 'darwin' and platform_machine == 'arm64'", "sys_platform == 'darwin' and platform_machine == 'x86_64'", ]
sources
-
类型:
dict
-
默认值:
{}
-
说明:用于解析依赖时的额外来源,可以是 Git 仓库、URL、本地路径或替代仓库。
-
示例:
[tool.uv.sources] httpx = { git = "https://github.com/encode/httpx", tag = "0.27.0" } pytest = { url = "https://files.pythonhosted.org/packages/6b/77/7440a06a8ead44c7757a64362dd22df5760f9b12dc5f11b6188cd2fc27a0/pytest-8.3.3-py3-none-any.whl" } pydantic = { path = "/path/to/pydantic", editable = true }
workspace
-
子配置:
exclude
:排除作为工作区成员的包。members
:包含作为工作区成员的包。
-
类型:
list[str]
-
默认值:
[]
-
说明:用于定义工作区成员,支持 glob 和显式路径。
-
示例:
[tool.uv.workspace] exclude = ["member1", "path/to/member2", "libs/*"] members = ["member1", "path/to/member2", "libs/*"]
Configuration
allow-insecure-host
-
类型:
list[str]
-
默认值:
[]
-
说明:允许与指定主机进行不安全的连接。可以指定主机名、主机端口对或 URL。警告:使用此选项会绕过 SSL 验证,可能会导致中间人攻击。
-
示例:
[tool.uv] allow-insecure-host = ["localhost:8080"]
cache-dir
-
类型:
str
-
默认值:
None
(默认路径为$XDG_CACHE_HOME/uv
或$HOME/.cache/uv
或%LOCALAPPDATA%\uv\cache
) -
说明:指定缓存目录的路径。
-
示例:
[tool.uv] cache-dir = "./.uv_cache"
cache-keys
-
类型:
list[dict]
-
默认值:
[{ file = "pyproject.toml" }, { file = "setup.py" }, { file = "setup.cfg" }]
-
说明:指定触发项目重建的文件或目录。支持文件、目录、Git 提交信息和环境变量。
-
示例:
[tool.uv] cache-keys = [{ file = "pyproject.toml" }, { file = "requirements.txt" }, { git = { commit = true } }]
check-url
-
类型:
str
-
默认值:
None
-
说明:在上传前检查索引 URL 中是否已存在相同文件,以避免重复上传。
-
示例:
[tool.uv] check-url = "https://test.pypi.org/simple"
compile-bytecode
-
类型:
bool
-
默认值:
false
-
说明:在安装后编译 Python 文件为字节码。默认情况下,字节码会在模块首次导入时懒加载编译。
-
示例:
[tool.uv] compile-bytecode = true
concurrent-builds
-
类型:
int
-
默认值:
None
(默认为可用 CPU 核心数) -
说明:同时构建源分发包的最大数量。
-
示例:
[tool.uv] concurrent-builds = 4
concurrent-downloads
-
类型:
int
-
默认值:
50
-
说明:同时下载的最大数量。
-
示例:
[tool.uv] concurrent-downloads = 4
concurrent-installs
-
类型:
int
-
默认值:
None
(默认为可用 CPU 核心数) -
说明:安装和解压包时使用的线程数。
-
示例:
[tool.uv] concurrent-installs = 4
config-settings
-
类型:
dict
-
默认值:
{}
-
说明:传递给 PEP 517 构建后端的配置设置。
-
示例:
[tool.uv] config-settings = { editable_mode = "compat" }
dependency-metadata
-
类型:
list[dict]
-
默认值:
[]
-
说明:为依赖项提供预定义的静态元数据。支持
name
、version
、requires-dist
、requires-python
和provides-extras
字段。 -
示例:
[tool.uv] dependency-metadata = [ { name = "flask", version = "1.0.0", requires-dist = ["werkzeug"], requires-python = ">=3.6" } ]
exclude-newer
-
类型:
str
-
默认值:
None
-
说明:限制候选包的上传时间,只选择在指定时间之前的包。支持 RFC 3339 时间戳和本地日期。
-
示例:
[tool.uv] exclude-newer = "2006-12-02"
extra-index-url
-
类型:
list[str]
-
默认值:
[]
-
说明:额外的包索引 URL,优先级高于
index-url
或index
中的默认索引。 -
示例:
[tool.uv] extra-index-url = ["https://download.pytorch.org/whl/cpu"]
find-links
-
类型:
list[str]
-
默认值:
[]
-
说明:额外的候选分发包位置,可以是本地目录或包含包文件链接的网页。
-
示例:
[tool.uv] find-links = ["https://download.pytorch.org/whl/torch_stable.html"]
fork-strategy
-
类型:
str
-
默认值:
"requires-python"
-
说明:在不同 Python 版本和平台上选择多个版本的包时的策略。可选值为
"fewest"
(选择最少版本)和"requires-python"
(选择最新版本)。 -
示例:
[tool.uv] fork-strategy = "fewest"
index
-
类型:
dict
-
默认值:
[]
-
说明:指定解析依赖时使用的包索引。支持 PEP 503 兼容的仓库或本地目录。索引的优先级由定义顺序决定。
-
示例:
[[tool.uv.index]] name = "pytorch" url = "https://download.pytorch.org/whl/cu121"
index-strategy
-
类型:
str
-
默认值:
"first-index"
-
说明:在多个索引 URL 中解析时的策略。可选值为
"first-index"
(仅使用第一个索引的结果)、"unsafe-first-match"
和"unsafe-best-match"
。 -
示例:
[tool.uv] index-strategy = "unsafe-best-match"
index-url
-
类型:
str
-
默认值:
"https://pypi.org/simple"
-
说明:默认的 Python 包索引 URL。优先级低于
extra-index-url
或index
中的索引。 -
示例:
[tool.uv] index-url = "https://test.pypi.org/simple"
keyring-provider
-
类型:
str
-
默认值:
"disabled"
-
说明:是否使用
keyring
提供身份验证。目前仅支持subprocess
模式。 -
示例:
[tool.uv] keyring-provider = "subprocess"
link-mode
-
类型:
str
-
默认值:
"clone"
(macOS)或"hardlink"
(Linux 和 Windows) -
说明:从全局缓存安装包时使用的方法。可选值为
"clone"
、"copy"
、"hardlink"
和"symlink"
。 -
示例:
[tool.uv] link-mode = "copy"
native-tls
-
类型:
bool
-
默认值:
false
-
说明:是否从平台的原生证书库加载 TLS 证书。默认情况下,使用内置的
webpki-roots
证书。 -
示例:
[tool.uv] native-tls = true
no-binary
-
类型:
bool
-
默认值:
false
-
说明:不安装预构建的 wheel 包,而是从源码构建和安装。
-
示例:
[tool.uv] no-binary = truef"]
no-binary-package
-
类型:
list[str]
-
默认值:
[]
-
说明:指定某些包不使用预构建的 wheel,而是从源码构建和安装。
-
示例:
[tool.uv] no-binary-package = ["ruff"]
no-build
-
类型:
bool
-
默认值:
false
-
说明:不构建源分发包。启用后,解析过程不会运行任意 Python 代码,而是直接使用缓存的 wheel。
-
示例:
[tool.uv] no-build = true
no-build-isolation
-
类型:
bool
-
默认值:
false
-
说明:在构建源分发包时禁用隔离。假设 PEP 518 指定的构建依赖已经安装。
-
示例:
[tool.uv] no-build-isolation = true
no-build-isolation-package
-
类型:
list[str]
-
默认值:
[]
-
说明:为特定包禁用构建隔离。假设这些包的 PEP 518 构建依赖已经安装。
-
示例:
[tool.uv] no-build-isolation-package = ["package1", "package2"]
no-build-package
-
类型:
list[str]
-
默认值:
[]
-
说明:不构建特定包的源分发包。
-
示例:
[tool.uv] no-build-package = ["ruff"]
no-cache
-
类型:
bool
-
默认值:
false
-
说明:不使用缓存,而是使用临时目录进行操作。
-
示例:
[tool.uv] no-cache = true
no-index
-
类型:
bool
-
默认值:
false
-
说明:忽略所有注册表索引(例如 PyPI),仅依赖于直接 URL 依赖项和通过
--find-links
提供的依赖项。 -
示例:
[tool.uv] no-index = true
no-sources
-
类型:
bool
-
默认值:
false
-
说明:忽略
tool.uv.sources
表中的依赖来源,仅使用标准的、可发布的包元数据。 -
示例:
[tool.uv] no-sources = true
offline
-
类型:
bool
-
默认值:
false
-
说明:禁用网络访问,仅依赖于本地缓存数据和本地文件。
-
示例:
[tool.uv] offline = true
prerelease
-
类型:
str
-
默认值:
"if-necessary-or-explicit"
-
说明:预发布版本的策略。可选值包括:
"disallow"
:禁止所有预发布版本"allow"
:允许所有预发布版本"if-necessary"
:如果包的所有版本都是预发布版本,则允许"explicit"
:仅允许显式标记为预发布的包"if-necessary-or-explicit"
:如果包的所有版本都是预发布版本,或者包的版本要求中显式标记为预发布,则允许
-
示例:
[tool.uv] prerelease = "allow"
preview
-
类型:
bool
-
默认值:
false
-
说明:是否启用实验性功能。
-
示例:
[tool.uv] preview = true
publish-url
-
类型:
str
-
默认值:
"https://upload.pypi.org/legacy/"
-
说明:发布包到 Python 包索引的 URL。
-
示例:
[tool.uv] publish-url = "https://test.pypi.org/legacy/"
pypy-install-mirror
-
类型:
str
-
默认值:
None
-
说明:用于下载 PyPy 安装的镜像 URL。默认情况下,从
downloads.python.org
下载。 -
示例:
[tool.uv] pypy-install-mirror = "https://downloads.python.org/pypy"
python-downloads
-
类型:
str
-
默认值:
"automatic"
-
说明:是否允许下载 Python。可选值包括:
"automatic"
:自动下载所需的 Python 安装"manual"
:需要手动安装 Python"never"
:禁止下载 Python
-
示例:
[tool.uv] python-downloads = "manual"
python-install-mirror
-
类型:
str
-
默认值:
None
-
说明:用于下载 Python 安装的镜像 URL。默认情况下,从
python-build-standalone
下载。 -
示例:
[tool.uv] python-install-mirror = "https://github.com/astral-sh/python-build-standalone/releases/download"
python-preference
-
类型:
str
-
默认值:
"managed"
-
说明:是否优先使用已安装的系统 Python,还是由 uv 下载和安装的 Python。可选值包括:
"only-managed"
:仅使用由 uv 管理的 Python 安装"managed"
:优先使用由 uv 管理的 Python 安装"system"
:优先使用系统 Python 安装"only-system"
:仅使用系统 Python 安装
-
示例:
[tool.uv] python-preference = "managed"
reinstall
-
类型:
bool
-
默认值:
false
-
说明:重新安装所有包,无论它们是否已经安装。此选项会隐式启用
refresh
。 -
示例:
[tool.uv] reinstall = true
reinstall-package
-
类型:
list[str]
-
默认值:
[]
-
说明:重新安装特定包,无论它们是否已经安装。此选项会隐式启用
refresh-package
。 -
示例:
[tool.uv] reinstall-package = ["ruff"]
required-version
-
类型:
str
-
默认值:
null
-
说明:强制 uv 的版本要求。如果运行时 uv 的版本不符合要求,将退出并报错。
-
示例:
[tool.uv] required-version = ">=0.5.0"
resolution
-
类型:
str
-
默认值:
"highest"
-
说明:解析依赖时选择兼容版本的策略。可选值包括:
"highest"
:选择最高兼容版本"lowest"
:选择最低兼容版本"lowest-direct"
:直接依赖选择最低兼容版本,间接依赖选择最高兼容版本
-
示例:
[tool.uv] resolution = "lowest-direct"
trusted-publishing
-
类型:
str
-
默认值:
"automatic"
-
说明:在 GitHub Actions 中配置可信发布。默认情况下,uv 会在 GitHub Actions 中检查可信发布。
-
示例:
[tool.uv] trusted-publishing = "always"
upgrade
-
类型:
bool
-
默认值:
false
-
说明:是否允许升级包,忽略现有输出文件中的固定版本。
-
示例:
[tool.uv] upgrade = true
upgrade-package
-
类型:
list[str]
-
默认值:
[]
-
说明:允许升级特定包,忽略现有输出文件中的固定版本。可以指定包名或版本范围。
-
示例:
[tool.uv] upgrade-package = ["ruff<0.5.0"]
pip
- 类型:
dict
- 默认值:
{}
(具体配置项见下文) - 说明:
uv pip
命令行界面的特定设置。这些设置仅在uv pip
命令中生效。
all-extras
-
类型:
bool
-
默认值:
false
-
说明:是否包含所有可选依赖项。仅适用于
pyproject.toml
、setup.py
和setup.cfg
源。 -
示例:
[tool.uv.pip] all-extras = true
allow-empty-requirements
-
类型:
bool
-
默认值:
false
-
说明:是否允许
uv pip sync
使用空的依赖项,这将清除环境中的所有包。 -
示例:
[tool.uv.pip] allow-empty-requirements = true
annotation-style
-
类型:
str
-
默认值:
"split"
-
说明:在输出文件中注释的样式。可选值为
"line"
(单行注释)和"split"
(每行一个注释)。 -
示例:
[tool.uv.pip] annotation-style = "line"
break-system-packages
-
类型:
bool
-
默认值:
false
-
说明:是否允许修改
EXTERNALLY-MANAGED
的 Python 安装。仅在 CI 环境中推荐使用。 -
示例:
[tool.uv.pip] break-system-packages = true
compile-bytecode
-
类型:
bool
-
默认值:
false
-
说明:是否在安装后编译 Python 文件为字节码。默认情况下,字节码会在模块首次导入时懒加载编译。
-
示例:
[tool.uv.pip] compile-bytecode = true
config-settings
-
类型:
dict
-
默认值:
{}
-
说明:传递给 PEP 517 构建后端的配置设置。
-
示例:
[tool.uv.pip] config-settings = { editable_mode = "compat" }
custom-compile-command
-
类型:
str
-
默认值:
None
-
说明:在
uv pip compile
生成的输出文件顶部添加的自定义编译命令。 -
示例:
[tool.uv.pip] custom-compile-command = "./custom-uv-compile.sh"
dependency-metadata
-
类型:
list[dict]
-
默认值:
[]
-
说明:为依赖项提供预定义的静态元数据。
-
示例:
[tool.uv.pip] dependency-metadata = [ { name = "flask", version = "1.0.0", requires-dist = ["werkzeug"], requires-python = ">=3.6" } ]
emit-build-options
**
- 类型:
bool
- 默认值:
false
- 说明:是否在
uv pip compile
生成的输出文件中包含--no-binary
和--only-binary
选项。 - 示例:
[tool.uv.pip]
emit-build-options = true
emit-find-links
-
类型:
bool
-
默认值:
false
-
说明:是否在
uv pip compile
生成的输出文件中包含--find-links
选项。 -
示例:
[tool.uv.pip] emit-find-links = true
emit-index-annotation
-
类型:
bool
-
默认值:
false
-
说明:是否在
uv pip compile
生成的输出文件中包含索引注释。 -
示例:
[tool.uv.pip] emit-index-annotation = true
emit-index-url
-
类型:
bool
-
默认值:
false
-
说明:是否在
uv pip compile
生成的输出文件中包含--index-url
和--extra-index-url
选项。 -
示例:
[tool.uv.pip] emit-index-url = true
emit-marker-expression
-
类型:
bool
-
默认值:
false
-
说明:是否在输出文件中包含标记表达式,指示依赖项有效的条件。
-
示例:
[tool.uv.pip] emit-marker-expression = true
exclude-newer
-
类型:
str
-
默认值:
None
-
说明:限制候选包的上传时间,仅选择在指定时间之前的包。
-
示例:
[tool.uv.pip] exclude-newer = "2006-12-02T02:07:43Z"
extra
-
类型:
list[str]
-
默认值:
[]
-
说明:包含的可选依赖项。仅适用于
pyproject.toml
、setup.py
和setup.cfg
源。 -
示例:
[tool.uv.pip] extra = ["dev", "docs"]
extra-index-url
-
类型:
list[str]
-
默认值:
[]
-
说明:额外的包索引 URL,优先级高于
index-url
。 -
示例:
[tool.uv.pip] extra-index-url = ["https://download.pytorch.org/whl/cpu"]
find-links
-
类型:
list[str]
-
默认值:
[]
-
说明:额外的候选分发包位置,可以是本地目录或包含包文件链接的网页。
-
示例:
[tool.uv.pip] find-links = ["https://download.pytorch.org/whl/torch_stable.html"]
fork-strategy
-
类型:
str
-
默认值:
"requires-python"
-
说明:在不同 Python 版本和平台上选择多个版本的包时的策略。
-
示例:
[tool.uv.pip] fork-strategy = "fewest"
generate-hashes
-
类型:
bool
-
默认值:
false
-
说明:是否在输出文件中包含分发包的哈希值。
-
示例:
[tool.uv.pip] generate-hashes = true
group
-
类型:
list[str]
-
默认值:
None
-
说明:指定要包含的依赖组。
-
示例:
[tool.uv.pip] group = ["dev", "docs"]
index-strategy
-
类型:
str
-
默认值:
"first-index"
-
说明:在多个索引 URL 中解析时的策略。可选值为:
"first-index"
:仅使用第一个索引的结果。"unsafe-first-match"
:在所有索引中搜索每个包名,优先使用第一个索引中的版本。"unsafe-best-match"
:在所有索引中搜索每个包名,选择最佳版本。
-
示例:
[tool.uv.pip] index-strategy = "unsafe-best-match"
index-url
-
类型:
str
-
默认值:
"https://pypi.org/simple"
-
说明:Python 包索引的 URL。此设置的优先级低于
extra-index-url
。 -
示例:
[tool.uv.pip] index-url = "https://test.pypi.org/simple"
keyring-provider
-
类型:
str
-
默认值:
"disabled"
-
说明:是否使用
keyring
提供身份验证。目前仅支持subprocess
模式。 -
示例:
[tool.uv.pip] keyring-provider = "subprocess"
link-mode
-
类型:
str
-
默认值:
"clone"
(macOS)或"hardlink"
(Linux 和 Windows) -
说明:从全局缓存安装包时使用的方法。可选值为:
"clone"
:使用 Copy-on-Write 模式。"copy"
:复制包。"hardlink"
:创建硬链接。"symlink"
:创建符号链接。
-
示例:
[tool.uv.pip] link-mode = "copy"
no-annotate
-
类型:
bool
-
默认值:
false
-
说明:是否在
uv pip compile
生成的输出文件中排除注释。 -
示例:
[tool.uv.pip] no-annotate = true
no-binary
-
类型:
list[str]
-
默认值:
[]
-
说明:指定不使用预构建的 wheel 包,而是从源码构建和安装。可以指定包名或
:all:
(禁用所有包的二进制安装)。 -
示例:
[tool.uv.pip] no-binary = ["ruff"]
no-build
-
类型:
bool
-
默认值:
false
-
说明:是否禁用源分发包的构建。启用后,解析过程不会运行任意 Python 代码。
-
示例:
[tool.uv.pip] no-build = true
no-build-isolation
-
类型:
bool
-
默认值:
false
-
说明:是否禁用构建源分发包时的隔离。假设 PEP 518 指定的构建依赖已经安装。
-
示例:
[tool.uv.pip] no-build-isolation = true
no-build-isolation-package
-
类型:
list[str]
-
默认值:
[]
-
说明:为特定包禁用构建隔离。假设这些包的 PEP 518 构建依赖已经安装。
-
示例:
[tool.uv.pip] no-build-isolation-package = ["package1", "package2"]
no-deps
-
类型:
bool
-
默认值:
false
-
说明:是否忽略包的依赖项,仅添加显式列出的包到结果依赖文件中。
-
示例:
[tool.uv.pip] no-deps = true
no-emit-package
-
类型:
list[str]
-
默认值:
[]
-
说明:指定要从输出解析中省略的包。其依赖项仍将包含在解析中。
-
示例:
[tool.uv.pip] no-emit-package = ["ruff"]
no-extra
-
类型:
list[str]
-
默认值:
[]
-
说明:如果启用了
all-extras
,则排除指定的可选依赖项。 -
示例:
[tool.uv.pip] all-extras = true no-extra = ["dev", "docs"]
no-header
-
类型:
bool
-
默认值:
false
-
说明:是否排除
uv pip compile
生成的输出文件顶部的注释头。 -
示例:
[tool.uv.pip] no-header = true
no-index
-
类型:
bool
-
默认值:
false
-
说明:是否忽略所有注册表索引(例如 PyPI),仅依赖于直接 URL 依赖项和通过
--find-links
提供的依赖项。 -
示例:
[tool.uv.pip] no-index = true
no-sources
-
类型:
bool
-
默认值:
false
-
说明:是否忽略
tool.uv.sources
表中的依赖来源,仅使用标准的、可发布的包元数据。 -
示例:
[tool.uv.pip] no-sources = true
no-strip-extras
-
类型:
bool
-
默认值:
false
-
说明:是否在输出文件中保留可选依赖项。默认情况下,可选依赖项会被移除。
-
示例:
[tool.uv.pip] no-strip-extras = true
no-strip-markers
-
类型:
bool
-
默认值:
false
-
说明:是否在输出文件中保留环境标记。默认情况下,环境标记会被移除。
-
示例:
[tool.uv.pip] no-strip-markers = true
only-binary
-
类型:
list[str]
-
默认值:
[]
-
说明:仅使用预构建的 wheel 包,不从源码构建。可以指定包名或
:all:
(仅使用所有包的二进制安装)。 -
示例:
[tool.uv.pip] only-binary = ["ruff"]
output-file
-
类型:
str
-
默认值:
None
-
说明:指定
uv pip compile
生成的依赖文件的输出路径。如果文件已存在,将优先使用现有版本进行解析,除非同时指定了--upgrade
。 -
示例:
[tool.uv.pip] output-file = "requirements.txt"
prefix
-
类型:
str
-
默认值:
None
-
说明:指定安装包的目标目录,类似于虚拟环境的结构。不推荐使用,因为安装的脚本将引用安装解释器,而不是目标目录中的解释器。
-
示例:
[tool.uv.pip] prefix = "./prefix"
prerelease
-
类型:
str
-
默认值:
"if-necessary-or-explicit"
-
说明:预发布版本的策略。可选值包括:
"disallow"
:禁止所有预发布版本。"allow"
:允许所有预发布版本。"if-necessary"
:如果包的所有版本都是预发布版本,则允许。"explicit"
:仅允许显式标记为预发布的包。"if-necessary-or-explicit"
:如果包的所有版本都是预发布版本,或者包的版本要求中显式标记为预发布,则允许。
-
示例:
[tool.uv.pip] prerelease = "allow"
python
-
类型:
str
-
默认值:
None
-
说明:指定安装包的目标 Python 解释器。支持以下格式:
3.10
:查找已安装的 Python 3.10(Windows 上的注册表或 Linux/macOS 上的python3.10
)。python3.10
或python.exe
:在PATH
中查找指定名称的二进制文件。/home/ferris/.local/bin/python3.10
:使用指定路径的 Python。
-
示例:
[tool.uv.pip] python = "3.10"
python-platform
-
类型:
str
-
默认值:
None
-
说明:指定解析依赖的目标平台,格式为“目标三元组”,例如
x86_64-unknown-linux-gnu
或aarch64-apple-darwin
。 -
示例:
[tool.uv.pip] python-platform = "x86_64-unknown-linux-gnu"
python-version
-
类型:
str
-
默认值:
None
-
说明:指定解析依赖时支持的最低 Python 版本,例如
3.8
或3.8.17
。如果省略补丁版本,则假定为最低补丁版本,例如3.8
表示3.8.0
。 -
示例:
[tool.uv.pip] python-version = "3.8"
reinstall
-
类型:
bool
-
默认值:
false
-
说明:是否重新安装所有包,无论它们是否已经安装。此选项隐式启用
refresh
。 -
示例:
[tool.uv.pip] reinstall = true
reinstall-package
-
类型:
list[str]
-
默认值:
[]
-
说明:重新安装特定包,无论它们是否已经安装。此选项隐式启用
refresh-package
。 -
示例:
[tool.uv.pip] reinstall-package = ["ruff"]
require-hashes
-
类型:
bool
-
默认值:
false
-
说明:是否要求每个依赖项都提供匹配的哈希值。启用后,所有依赖项都必须提供哈希值,并且必须是固定版本(例如
==1.0.0
)或通过直接 URL 指定。 -
示例:
[tool.uv.pip] require-hashes = true
resolution
-
类型:
str
-
默认值:
"highest"
-
说明:解析依赖时选择兼容版本的策略。可选值包括:
"highest"
:选择最高兼容版本。"lowest"
:选择最低兼容版本。"lowest-direct"
:直接依赖选择最低兼容版本,间接依赖选择最高兼容版本。
-
示例:
[tool.uv.pip] resolution = "lowest-direct"
strict
-
类型:
bool
-
默认值:
false
-
说明:是否验证 Python 环境,检测缺少依赖项和其他问题。
-
示例:
[tool.uv.pip] strict = true
system
-
类型:
bool
-
默认值:
false
-
说明:是否将包安装到系统 Python 环境中。默认情况下,uv 会安装到当前工作目录或父目录中的虚拟环境中。
-
示例:
[tool.uv.pip] system = true
target
-
类型:
str
-
默认值:
None
-
说明:指定将包安装到的目标目录,而不是安装到虚拟环境或系统 Python 环境中。包将安装到目录的顶层。
-
示例:
[tool.uv.pip] target = "./target"
torch-backend
-
类型:
str
-
默认值:
null
-
说明:指定 PyTorch 生态系统中使用的后端。可选值包括:
cpu
:使用 CPU-only 的 PyTorch 索引。cu126
:使用 CUDA 12.6 的 PyTorch 索引。auto
:自动检测当前安装的 CUDA 驱动程序并选择合适的 PyTorch 索引。
-
示例:
[tool.uv.pip] torch-backend = "auto"
universal
-
类型:
bool
-
默认值:
false
-
说明:是否执行通用解析,尝试生成一个兼容所有操作系统、架构和 Python 实现的单一
requirements.txt
文件。在通用模式下,当前 Python 版本(或用户指定的--python-version
)将被视为下限。 -
示例:
[tool.uv.pip] universal = true
upgrade
-
类型:
bool
-
默认值:
false
-
说明:是否允许升级包,忽略现有输出文件中的固定版本。
-
示例:
[tool.uv.pip] upgrade = true
upgrade-package
-
类型:
list[str]
-
默认值:
[]
-
说明:允许升级特定包,忽略现有输出文件中的固定版本。可以指定包名或版本范围。
-
示例:
[tool.uv.pip] upgrade-package = ["ruff<0.5.0"]
verify-hashes
-
类型:
bool
-
默认值:
true
-
说明:是否验证要求文件中提供的哈希值。与
require-hashes
不同,此选项不会要求所有依赖项都提供哈希值,而是仅验证那些提供了哈希值的依赖项。 -
示例:
[tool.uv.pip] verify-hashes = true