在python uv中设置清华源,最直接的方法是使用环境变量 uv_index_url 或 uv_extra_index_url。通过设置 uv_index_url=https://pypi.tuna.tsinghua.edu.cn/simple,可以将默认索引指向清华镜像;若需保留官方源作为备用,可设置 uv_extra_index_url。配置完成后,执行 uv pip install 命令时,工具会自动从指定源拉取包。

如何通过环境变量临时指定清华源?
可以通过在命令行中直接导出环境变量来临时指定清华源。这种方式无需修改配置文件,适合一次性测试或特定脚本使用。设置后,后续的 uv 命令都会优先使用该源。

export UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple" uv pip install requests
上述代码中,export 命令将 UV_INDEX_URL 设置为清华镜像地址。接着运行 uv pip install requests,uv 会向该URL发起请求并安装 requests 包。如果网络通畅,安装速度将显著提升。注意,环境变量仅在当前终端会话中有效,关闭终端后需重新设置。
立即学习“Python免费学习笔记(深入)”;
将测试、lint、构建和文档流程编码为命名的Python会话,以便人类和代理每次运行相同的workflow。
如何永久配置清华源到项目文件中?
若希望项目在任意环境下都使用清华源,可将配置写入项目的 pyproject.toml 文件。这种方法便于团队协作,确保所有开发者使用相同的依赖源。在 [tool.uv.index] 部分定义默认索引即可。

[tool.uv]
index_url = "https://pypi.tuna.tsinghua.edu.cn/simple"
[tool.uv.indexes]
default = { url = "https://pypi.tuna.tsinghua.edu.cn/simple" }
在 pyproject.toml 中添加上述配置后,uv 会在读取项目配置时自动应用清华源。这种方式比环境变量更持久,且能随项目版本控制一起提交。若需同时使用多个源,可在 [tool.uv.extra-indexes] 中追加其他镜像地址。配置生效后,uv sync 或 uv pip install 均会优先从清华源下载依赖。
当清华源返回404错误时如何处理?
如果在使用清华源时遇到 404 Not Found 错误,通常是因为某些小众包未同步至镜像站。此时应切换回官方PyPI源或启用备用索引。可通过临时移除环境变量或注释掉 pyproject.toml 中的镜像配置来恢复默认行为。
# 临时切换回官方源 unset UV_INDEX_URL uv pip install some-rare-package
上述代码中,unset 命令清除了之前设置的环境变量,使 uv 恢复使用官方PyPI源。对于 some-rare-package 这类可能不在镜像站的包,直接访问官方源可避免404错误。建议在开发环境中保持镜像源为主、官方源为备的策略,以兼顾速度与兼容性。

















