配置python uv 的核心在于设置环境变量 uv_index_url 和 uv_extra_index_url,将包源指向公司内网的镜像服务器。通过这种方式,uv 在解析依赖时会自动优先或仅从内网地址拉取包,从而绕过公网限制并提升下载速度。

如何指定主索引源为内网地址
要让 uv 默认使用内网源,需设置 UV_INDEX_URL 环境变量。该变量对应 PyPI 的主索引地址,设置后所有未显式指定源的包安装请求都会指向该 URL。例如,若内网镜像地址为 http://internal.pypi/simple,则执行 export UV_INDEX_URL=http://internal.pypi/simple 即可生效。此操作确保基础依赖解析完全在内网环境中进行。

export UV_INDEX_URL=http://internal.pypi/simple uv pip install requests
运行上述命令后,uv 会向 http://internal.pypi/simple 发起请求获取 requests 的元数据。如果内网镜像完整同步了公网包,安装将成功且速度显著快于公网。若内网缺失某包,且未配置额外源,安装将失败并提示找不到包。
如何处理公网特有或内网缺失的依赖
当部分依赖在内网镜像中不存在时,可通过 UV_EXTRA_INDEX_URL 配置备用公网源。该变量允许 uv 在查询主索引无果时,继续查询额外索引地址。设置方法为 export UV_EXTRA_INDEX_URL=https://pypi.org/simple。结合主内网源,uv 会先查内网,再查公网,实现混合源策略。注意,若内网镜像已包含所有所需包,建议关闭此选项以保障安全与速度。

export UV_INDEX_URL=http://internal.pypi/simple export UV_EXTRA_INDEX_URL=https://pypi.org/simple uv pip install internal-lib,public-lib
在此配置下,uv 首先尝试从 http://internal.pypi/simple 获取 internal-lib 和 public-lib。若 internal-lib 在内网存在,则直接安装;若 public-lib 在内网不存在,uv 会自动回退到 https://pypi.org/simple 进行下载。这种机制确保了依赖解析的灵活性,同时优先利用内网资源。
内网镜像未同步特定版本时的行为验证
若内网镜像未同步某个包的特定版本,uv 的行为取决于是否配置了 UV_EXTRA_INDEX_URL。在未配置额外源的情况下,uv 仅查询 UV_INDEX_URL 指定的内网地址。若内网中该包的可用版本列表不包含请求版本,uv 将抛出 No matching distribution 错误。即使公网存在该版本,由于未启用额外源,uv 不会自动跨源查找。因此,确保内网镜像覆盖项目所需的所有包版本是关键。若必须访问公网特定版本,需启用 UV_EXTRA_INDEX_URL,但需注意潜在的安全策略合规性。
Python免费学习笔记(深入):立即使用
在学习笔记中,你将探索 Python 的核心概念和高级技巧!











