配置文件

uv 的配置文件分为项目级别和用户级别、系统级别三个级别。项目级别的配置通常是通过项目目录或者项目上级目录中的pyprojet.toml和uv.toml文件来定义的。用户级别配置通常放置在用户家目录（Home Directory）中的~/.config/uv/uv.toml文件中。系统级配置通常放在/etc/uv/uv.toml文件中。

一般来说，在项目目录中的 uv 配置通常不会独立放置在uv.toml文件中，而是放在pyproject.toml文件的[tool.uv]配置节中。如果pyproject.toml文件中没有出现[tool.uv]的配置内容，uv 才会去寻找uv.toml文件。

除了配置文件以外，uv run在运行的时候还可以加载项目目录中的环境变量文件。环境变量文件可以通过--env-file参数来加载，或者是设定环境变量UV_ENV_FILE来使uv run命令找到所需要加载的环境变量文件。如果设定加载了多个环境变量文件，那么后加载的环境变量文件会覆盖先加载的环境变量文件。

常用配置项目

这里列举的常用配置项目不是用在pyproject.toml的[project]配置段中的，而是用在[tool]配置段中的。以下配置项目在说明其功能的时候会指明其具体配置段名称。

index

index 配置是用来解决依赖项的索引，通常会配置为一个符合 PEP 503 规定的存储库，或者是一个本地地址。一个 index 项目通常需要至少配置一个name和一个url。

例如以下配置：

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

[[tool.uv.index]]这里使用双层[]的原因是做一个配置文件中可以配置 uv 使用多个index，所以根据 TOML 文件的语法，[[]]实际上声明的是一个列表。所以这里要注意的是，在配置了多个index的时候，uv 会优先使用先定义的index，除非其中某一个index中标注了default = true。

在[[tool.uv.index]]中常见的配置还有explicit = true，采用了这个标记的index，只能被用在[[tool.uv.sources]]中显式的为指定依赖项设定检索索引。例如：

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

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

并行任务配置

并行任务配置主要是用来配置 uv 如何并行的处理任务，常用配置有三个：

  • concurrent-builds，用于设置 uv 并行构建的数量，通常与 CPU 核心数目相同。
  • concurrent-downloads，用于配置 uv 并行执行下载任务的数量，默认值为 50。
  • concurrent-installs，用于配置 uv 进行包的安装和解压所使用的线程数量，通常与 CPU 核心数目相同。

这三个配置通常直接放置在uv.toml中或者pyproject.toml的[tool.uv]下。

native-tls

设置 uv 是否需要从平台原生证书库加载 TLS 证书。uv 默认设置此项配置为false，并从webpki-roots包中加载证书。设定为true可以在部分平台上，在一定程度下提升性能。

no-binary

设置 uv 在安装包的时候，不安装预编译的二进制包，而是完全从源代码开始编译和安装。默认此项设置为false。

no-binary设定的是 uv 获取和安装包的全局配置，如果只需要在处理部分包的时候不安装二进制与编译包，那么可以使用no-binary-package来指定不安装预编译包的包名称。

pypy-install-mirror

设定 uv 在下载 Pypy 的时候使用的安装镜像位置。

python-downloads

设定是否允许 uv 下载 Python 发行版来部署 Python 运行环境。这个配置项可以取三个值：

  • automatic，根据需要自动下载 Python 安装包。
  • manual，不自动下载 Python 安装包，需要显式指定安装。
  • never，禁止自动下载任何 Python 安装包。

python-install-mirror

用于设定用来下载 Python 安装包的镜像站 URL。

upgrade

用于设定是否允许自动升级依赖库，默认为false，如果设定为true，那么将会忽略配置文件中固定的包版本。

使用upgrade-package可以单独设定部分包为自动升级，而不是通过upgrade在全局设定所有的包为自动升级。

pip 配置

pip 配置是uv.toml文件中独立的配置段，在配置的时候需要使用[pip]标记。如果在pyproject.toml中配置，那么需要在[tool.uv.pip]中配置。

pip 中的配置大多与上面 uv 的配置相同，常用的配置主要是index-url用来配置 pip 从何处索引获取依赖库信息。