青蛙小白
博客 / 2025/03

uv的环境变量

2025/03/27 · — 字 · 阅读约 — 分钟 ·
#python
目录

uv的文档“Environment variables”中详细的给出了uv自己定义使用的和uv遵循使用的环境变量。

这里记录个人平时经常使用的一些环境变量。

UV_PYTHON_INSTALL_MIRROR

uv管理的Python安装包是从python-build-standalone项目下载的。

环境变量UV_PYTHON_INSTALL_MIRROR可以设置为镜像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方案，也可以从本地目录读取发行版文件。

export UV_PYTHON_INSTALL_MIRROR=https://gh-proxy.com/github.com/indygreg/python-build-standalone/releases/download
uv python install 3.13

UV_DEFAULT_INDEX

相当于命令行参数--default-index。如果设置了该环境变量，uv 在搜索软件包时将使用此 URL 作为默认索引。

一般在使用uv tool安装工具时使用它。例如:

export UV_DEFAULT_INDEX=https://mirrors.aliyun.com/pypi/simple
uv tool install --python 3.12 -v s3cmd

s3cmd被安装在~/.local/share/uv/tools/s3cmd目录中。同时创建了~/.local/bin/s3cmd到~/.local/share/uv/tools/s3cmd/bin/s3cmd的软连接。

UV_INDEX_{name}_USERNAME和UV_INDEX_{name}_PASSWORD

UV_INDEX_{name}_USERNAME为指定名称的索引提供HTTP基本认证所需的用户名。其中，name是该索引的名称。例如，如果索引名为foo，则对应的环境变量键应为UV_INDEX_FOO_USERNAME。

UV_INDEX_{name}_PASSWORD为指定名称的索引提供HTTP基本认证所需的密码。其中，name是该索引的名称。例如，如果索引名为foo，则对应的环境变量键应为UV_INDEX_FOO_PASSWORD。

默认情况下，uv使用PyPI进行依赖解析和包安装。可以通过 pyproject.toml 文件中的 [[tool.uv.index]] 配置选项（或命令行参数 --index）来使用其他包索引源，包括私有源。

这对于需要使用公司内部私有包仓库或者国内镜像源的用户来说非常实用。

[[tool.uv.index]]
name = "private-pypi"
# url = "https://mirrors.aliyun.com/pypi/simple/"
url = "https://pypi.example.com/repository/pypi-public/simple"
default = true

如果指定的pypi是私有仓库，并且开启了认证，可以使用这2个环境变量为私有pypi指定用户名和密码。这对于在做持续集成CI配置时十分有用。

export UV_INDEX_PRIVATE_PYPI_USERNAME=username
export UV_INDEX_PRIVATE_PYPI_PASSWORD=password

UV_DEV 和 UV_NO_DEV 环境变量

uv 0.8.8新增的环境变量

这两个环境变量提供了一种灵活的方式来控制是否在安装或同步依赖时包含开发依赖项（通常在 pyproject.toml 的 [tool.uv.dev-dependencies] 中定义）。它们分别对应 --dev 和 --no-dev 命令行参数。

UV_DEV

  • 作用: 强制包含开发依赖。
  • 使用场景: 当你需要确保开发依赖被安装时，可以在执行命令前设置此环境变量。

UV_NO_DEV

  • 作用: 强制排除开发依赖。
  • 使用场景: 这是两者中更有用的一个，特别是在生产环境或 CI/CD 流程中。默认情况下，uv sync 或 uv pip install 会安装开发依赖，但在构建生产镜像或部署应用时，你通常希望跳过这些非必需的包（如 pytest, ruff 等），以减小最终产物的大小。

示例:

假设 pyproject.toml 如下:

[project]
name = "my-app"
version = "0.1.0"
dependencies = [
  "fastapi",
]

[tool.uv.dev-dependencies]
pytest = ">=8.0"

  • 默认行为 (安装所有依赖):

    uv pip install -r requirements.txt 
# 或者
uv sync
# 这会安装 fastapi 和 pytest

  • 使用 UV_NO_DEV (仅安装生产依赖):

    export UV_NO_DEV=1
uv sync
# 这只会安装 fastapi，pytest 会被跳过

    或者，你也可以在单条命令前使用它：

    UV_NO_DEV=1 uv sync

这种方式比在每个 uv 命令后都添加 --no-dev 标志要方便得多，尤其是在自动化脚本中。

TAGS # python
评论