
uv环境配置应优先使用环境变量取代uv.toml,仅仅需要关注两个配置项,就可以快速的上手Python的开发。
写在前面: 如果你是 Python 开发者,过去几年你大概率在 pip、conda、poetry、pipenv 之间辗转折腾过。每一款工具都有其擅长之处,但也都有令人抓狂的短板——要么速度慢,要么锁文件混乱,要么 Python 版本管理和包管理是两套割裂的体系。 直到 uv 的出现。 这款由 Astral 团队(也是 Ruff 代码检查器的作者)用 Rust 编写的工具,野心极大:它要成为 Python 生态中那个"统一的瑞士军刀"——一个工具替代 pip、pip-tools、pipx、poetry、pyenv、virtualenv 的全部功能,同时速度快出一个数量级。 在复杂的工程实践中,开发者常面临网络代理限制、系统盘空间不足、跨平台环境不一致等痛点。uv 虽然提供了 uv.toml 配置文件,但由于其设计上的"非对称性"(部分核心路径如 Python 安装目录仅支持环境变量),为了实现配置方式的绝对统一和最大的灵活性,本文推荐完全抛弃 uv.toml,统一使用系统级环境变量来管理 uv。
先前一直使用rye进行Python的项目构建和管理,但是在2025年2月,官方停止了维护,推荐全面切换到uv进行管理。在实际开发中,我真正需要关心的配置其实并不多,核心只有两个路径:Python 解释器装在哪、依赖缓存存在哪。此外,网络代理在开发中几乎是必配项;而对于机器学习场景,还需要额外处理 PyTorch 等特殊包的安装源。抓住这四个方向,uv 的配置就基本覆盖了绝大多数日常使用场景。
uv 的设计中存在一个关键的配置差异:
这种不统一意味着,如果你依赖 uv.toml,你依然无法完整配置 uv 的所有行为。统一使用环境变量 (Environment Variables) 是目前最专业、最无歧义的深度定制方案。
通过环境变量,我们可以轻松将 uv 的大数据目录(Python 版本和缓存)从系统 C 盘移走。
当你执行 uv python install 时,uv 会从 python-build-standalone 项目下载预编译的 Python 发行版。
uv 的高速依赖解析完全依赖本地缓存。
这是 uv 目前最依赖环境变量的部分。由于 uv 内部不提供独立的代理开关,它直接继承 shell 的标准代理变量。不过我个人认为,考虑到现实中网络环境的复杂性——企业内网、科研机构的隔离网络、家庭代理各有不同——uv 日后或许有必要将代理参数作为一等公民纳入其配置体系,而不是完全依赖 shell 级别的环境变量继承。我当前采取的方法:每次在执行uv add或者uv sync时,预先在当前shell中设定代理配置。
如果你处于公司内网或需要特殊网络环境安装包,请直接在环境变量中指定:
虽然抛弃了全局的 uv.toml,但在项目级别,仍然需要在 pyproject.toml 中通过 [[tool.uv.index]] 来管理特定的安装源(如 PyTorch 的 CUDA 源)。这是项目依赖逻辑的一部分,而非工具本身的偏好设置。
配置好 pyproject.toml 后,执行以下命令安装依赖:
注意:torch、torchvision、torchaudio 三者版本需严格对应,混用不同版本极易引发运行时错误。建议始终在 pyproject.toml 中同步锁定三者的版本下界。
既然已经统一了环境变量,所有的维护操作就变得非常透明:
uv 以极速的依赖解析和统一的工具链,带来了前所未有的开发效率,令人爱不释手。然而,繁多的配置项也确实让初次上手的开发者感到眼花缭乱,无从下手。
本文的核心观点只有一个:全面拥抱环境变量,放弃 uv.toml。这一策略不仅覆盖了所有配置场景(包括 uv.toml 无法支持的 Python 安装路径与代理设置),还让工具配置与系统级设置高度统一,清晰可查。