【开源自荐】uv-custom 国内直连的 uv + uv python 镜像
- 内容介绍
- 文章标签
- 相关推荐
本帖使用社区开源推广，符合推广要求。我申明并遵循社区要求的以下内容：
- 我的帖子已经打上 开源推广 标签： 是
- 我的开源项目完整开源，无未开源部分： 是
- 我的开源项目已链接认可 LINUX DO 社区： 是
- 我帖子内的项目介绍，AI生成、润色内容部分已截图发出： 是
- 以上选择我承诺是永久有效的，接受社区和佬友监督： 是
以下为项目介绍正文内容，AI生成、润色内容已使用截图方式发出
首先说一些前言废话，有感而发，如果不感兴趣可直接跳至正文：
从已归档的帖子【开源分享】uv-custom 在国内网络下一键安装uv 附带uv和mamba/conda联动HOOK脚本 继续讨论：
目前来说，对于使用 AI 进行开发，哪怕不是进行开发的佬友们，uv 应该是无人不知无人不晓的存在了。
最快速的依赖管理，最适合 AI 启动的 python 虚拟环境，最简单的 python runtime 安装，最适合 AI 临时运行各种 python 脚本的 CLI 工具（这点在 Skill 大爆发后显得尤为重要），以及最适合发布到 pypi 的 publish 管理器，uv 可谓是新时代 python 包管理和环境管理、运行时管理的事实标准。以上内容纯属虚构，不适用广告法
而时间倒退到已归档的帖子发布的时候 2025年6月，彼时还属于 Coding Agent 没有进入 iPhone 时刻的年头，大家都在艰难探索和 AI 共生的经验。而对于 uv ，很多人的了解其实也并不深。
我也是探索的一员，而在当时因为一个小需求 （被迫不得已的要在国内环境下安装和使用 uv），萌生了启动 uv-custom 这样一个方便自己和大家在国内下载和使用 uv 以及 uv python install 的项目的念头。
艰难地配合 Cursor 反复修改，发布了第一个版本。当时的项目也在 L 站发布了帖子，获得了一些佬友的支持，也获得了一些 Github 和 Gitee 上朋友们的喜爱。不过实话实说，这个项目其实并不能称得上是“uv 的国内镜像”，仅仅是掺和了一个 Github 代理进去（而且当时用的代理也因为某些原因放弃继续做下去了，而我又没有及时更换），重打包脚本的水平也非常低下。
如今时隔一年，经过各种大小项目的洗礼，也从 L 站佬友这获得了不少信息差和资源，申请白嫖到了中科院高能物理所的免费 1TB 的 S3，于是有技术和条件，真正的去做一个国内的 uv 镜像了。
希望能帮到和我有同样需求的佬友们，也谢谢在 L 站学习过程中遇到的无私奉献和分享的佬友们。学 AI，上L站，此言非虚。
image1920×1072 187 KB
uv-custom 面向中国大陆用户的公益镜像入口
如果你有使用 uv standalone（而不是 pip install uv ) 的需求，大概率能理解这种体验：
你明明已经选了一个足够现代、足够快、足够顺手的 Python 管理工具，但到了某些特殊情况只能在国内网络直连的条件下落地时，问题却不是出在 uv 本身，而是出在下载不下来（
有时候是安装脚本拉不下来（不过目前 uv 官方的安装脚本已经对大陆网络环境相对友好了）。
有时候是 uv python install 依赖的运行时下载不下来，因为它直连 uv 的 GitHub Release。这一点很重要，因为很多人已经放弃直接去 python.org 下载官方构建了，uv 这一套实在是太方便了。一台裸机配 python 环境，只需要一个 uv 和一些命令行，天然适合 AI Agent。
有时候是 uv add、uv sync、uv pip install 背后的 PyPI 访问出问题，哪怕你已经换了清华源等国内镜像。
这些问题让希望用 uv 减少配 python 环境时候的烦恼的用户感觉一朝回到解放前，如果你将 uv 推荐给你的朋友们，而他们恰巧又是在国内的网络环境下，他们甚至会怀疑是你的眼光有问题（这也是我的真实体验
对于我自己来说，当我需要讲一些公开培训课的时候，我需要统一给在场用户安装 python 环境，而我又不可能统一给在场用户安装**……于是 uv-custom 的国内环境安装脚本和 python build 镜像就很有价值了。
这就是 uv-custom 想解决的问题。
一个更贴近官方体验的大陆入口
uv-custom 是一个面向中国大陆的 uv 公益镜像入口。
这个项目没有重新发明一套安装方式，相反，这个项目的实现尽量做到了最小改动和克制：
尽量保持 uv 官方使用方式不变，只把最容易出问题的下载链路，换成更适合中国大陆网络环境的入口。
这个项目做了什么
uv-custom 主要做了四件事：
- 同步官方 uv release 的二进制本体 和 installer 脚本
- 同步 uv python install 需要的 python 运行时 Github Release 资产
- 提供一个统一的大陆可用安装入口（小文件如脚本等，走 CF worker，大文件走 S3 直连）
- 提供一个适合 uv / pip 使用的 PyPI Simple 代理入口（避免出现 pip 已经换源但 uv add 等等需要 simple 和 *.metadata 等清华源之类的镜像都没有镜像到的情况）
因此，uv-custom 解决是一整条实际使用链路：
从第一次安装 uv，到安装 Python 运行时，再到后续 add、lock、sync、pip install 时访问包索引和文件下载，这些环节都尽量接到国内可直接访问的稳定入口上。
它稳定吗？
我觉得还可以，因为有两点保证：
1. 不硬改官方安装器，而是尽量复用官方路径
项目提供的大陆可用的安装入口，并不是自己重写一整套安装逻辑，而是尽量复用官方 installer，再通过环境变量和配置，把后续下载来源切到镜像，做到最小改动，后续也好维护。
Github Action 固定轮询 uv 官方仓库，有新 release 就同步过去，目前看 CI 是一片绿的，看着就挺稳的（
image2300×1518 277 KB
2. 够重的 smoke test
由于有真实的用户拿着鞭子抽 （不是），这个项目的 smoke test 设计的时候非常重视“真实链路能不能跑通”，不只停留在函数级测试。
我在 Github 的 CI 上写了一个 smoke_matrix ，它会在 Linux、macOS、Windows 上清空环境后真实安装 uv、检查 profile 和 uv.toml、再跑一轮重依赖安装；uv_smoke.py 甚至故意把依赖拆成多次 uv add，还单独拉一次 torch 这种大包，尽量模拟真正的初始安装环境。
另外我也在我自己的上海 Ubuntu 服务器上进行了真实的联调测试（由 Agent 代劳），同样通过。
顺便我还拿我的学员们当做小白鼠 （不是） 做了线下的真实联调测试，效果很好。
它适合哪些人
如果你属于下面几类用户，我觉得这个项目应该会有帮助：
- 不得不在中国大陆使用 uv 的开发者
- 需要更稳定完成 uv python install 的用户
- 经常使用 uv add、uv sync、uv pip install，踩过坑的用户
- 想给企业国内网络环境下的团队提供一个更统一、更省心的 uv 接入方式的用户
如何使用
macOS / Linux
curl -LsSf https://uv.agentsmirror.com/install-cn.sh | sh
Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://uv.agentsmirror.com/install-cn.ps1 | iex"
安装完成后，它会把后续相关配置也接好，让 uv 本体安装、Python 运行时下载，以及默认的 PyPI 访问（清华源）都走更适合大陆环境的入口。
最后
本人承诺本项目完全开源，遵守 MIT LICENSE，不会有任何盈利的性质。如果遇到 S3 不稳定、域名过期等问题，会及时进行处理，切到备份方案等。
希望各位佬友指出本项目存在的不足，也欢迎 issue 和 pr，如有帮助，也希望能动动小手点个 star。如果有更多的需求，也欢迎在 issue 中提出来，感谢！
Github 仓库地址：
GitHub - Wangnov/uv-custom: 一个 uv 公益镜像，提供国内的 uv 和 uv python runtime 高速下载
一个 uv 公益镜像，提供国内的 uv 和 uv python runtime 高速下载
网友解答：--【壹】--：
这个我晓得，好几年前找到过的唯一一家，到目前为止可能也是唯一一家做了 python build 的镜像了吧，不过当时我用的时候发现版本不全，后面就没有再继续用。
--【贰】--：
uv 配置镜像源不也挺方便的吗，每次在 toml 里面加上就好了
--【叁】--：
toml里面配置的是pip/uv add的源，uv安装python版本的话还是从github上面拉的
--【肆】--：
感谢提醒，我找找看，如果有的话切过去兜底
--【伍】--：
看到torch了
首先国内镜像站 默认路径（版本）是 cu126
不同的特定版本 好像阿里开源站有个专门的wheel站 这块用的少不属性
其次 uv官方专门有个页面讲了不同的extra 对应不同的torch 方便打包
--【陆】--： Wangnov:
Wangnov:
- 不硬改官方安装器，而是尽量复用官方路径
- 够重的 smoke test
我感觉我废了，看谁的大段文章都感觉是GPT写的
不过还是得支持一下
--【柒】--：
NJU Mirror
用手机搜了下
uv也有官方镜像 Using uv in Docker | uv
一般我会打镜像会copy from 复制到 user/local/bin 下使用再配合国内源安装python运行环境
--【捌】--：
用了好久了我 基本上服务器 电脑我都装的佬的
我说最近咋没有发行版原来是搞大事情去了 佬牛牛
--【玖】--：
这个配置的不止是 pip 镜像源的，pip 确实不麻烦
--【拾】--：
uv python install 国内有镜像源
嗯 具体地址不记得 清华源的右下角 有个联合搜索 进去搜
--【拾壹】--：
支持一下。我个人每次都是直接开TUN模式，所有的命令就都没有问题了，也不需要配置镜像。
--【拾贰】--：
有空试试看，之前用uv安装torch，虽然设置了镜像还是有点慢，看看佬的好不好使
--【拾叁】--：
佬造福于大家！！！虽然暂时用不到，但是收藏了，难保以后。现在越来越收紧了。
--【拾肆】--：
大概是因为我天天用 GPT，所以被它带坏了语言习惯。不用怀疑，确实是手写的。请把不是而是还给人类
--【拾伍】--：
感谢大佬，突然就想到我的那个空闲存储可以用来做什么了。
--【拾陆】--：
确实，我也是只发现仅此一家。不过现在我也把它镜像了，就有二家了哈哈哈（虽然我只镜像了最新版，但是矩阵是全的）
--【拾柒】--：
去年有段时间版本更新不及时 但好像一般ARM和x86都有 最近几个月感觉还不错
国内独此一家 我也找遍了
为了打镜像 试过修改元数据yaml文件绕过去
最后还是自己打个包含常用python版本的镜像自用
后面恢复了就直接用了
本帖使用社区开源推广，符合推广要求。我申明并遵循社区要求的以下内容：
- 我的帖子已经打上 开源推广 标签： 是
- 我的开源项目完整开源，无未开源部分： 是
- 我的开源项目已链接认可 LINUX DO 社区： 是
- 我帖子内的项目介绍，AI生成、润色内容部分已截图发出： 是
- 以上选择我承诺是永久有效的，接受社区和佬友监督： 是
以下为项目介绍正文内容，AI生成、润色内容已使用截图方式发出
首先说一些前言废话，有感而发，如果不感兴趣可直接跳至正文：
从已归档的帖子【开源分享】uv-custom 在国内网络下一键安装uv 附带uv和mamba/conda联动HOOK脚本 继续讨论：
目前来说，对于使用 AI 进行开发，哪怕不是进行开发的佬友们，uv 应该是无人不知无人不晓的存在了。
最快速的依赖管理，最适合 AI 启动的 python 虚拟环境，最简单的 python runtime 安装，最适合 AI 临时运行各种 python 脚本的 CLI 工具（这点在 Skill 大爆发后显得尤为重要），以及最适合发布到 pypi 的 publish 管理器，uv 可谓是新时代 python 包管理和环境管理、运行时管理的事实标准。以上内容纯属虚构，不适用广告法
而时间倒退到已归档的帖子发布的时候 2025年6月，彼时还属于 Coding Agent 没有进入 iPhone 时刻的年头，大家都在艰难探索和 AI 共生的经验。而对于 uv ，很多人的了解其实也并不深。
我也是探索的一员，而在当时因为一个小需求 （被迫不得已的要在国内环境下安装和使用 uv），萌生了启动 uv-custom 这样一个方便自己和大家在国内下载和使用 uv 以及 uv python install 的项目的念头。
艰难地配合 Cursor 反复修改，发布了第一个版本。当时的项目也在 L 站发布了帖子，获得了一些佬友的支持，也获得了一些 Github 和 Gitee 上朋友们的喜爱。不过实话实说，这个项目其实并不能称得上是“uv 的国内镜像”，仅仅是掺和了一个 Github 代理进去（而且当时用的代理也因为某些原因放弃继续做下去了，而我又没有及时更换），重打包脚本的水平也非常低下。
如今时隔一年，经过各种大小项目的洗礼，也从 L 站佬友这获得了不少信息差和资源，申请白嫖到了中科院高能物理所的免费 1TB 的 S3，于是有技术和条件，真正的去做一个国内的 uv 镜像了。
希望能帮到和我有同样需求的佬友们，也谢谢在 L 站学习过程中遇到的无私奉献和分享的佬友们。学 AI，上L站，此言非虚。
image1920×1072 187 KB
uv-custom 面向中国大陆用户的公益镜像入口
如果你有使用 uv standalone（而不是 pip install uv ) 的需求，大概率能理解这种体验：
你明明已经选了一个足够现代、足够快、足够顺手的 Python 管理工具，但到了某些特殊情况只能在国内网络直连的条件下落地时，问题却不是出在 uv 本身，而是出在下载不下来（
有时候是安装脚本拉不下来（不过目前 uv 官方的安装脚本已经对大陆网络环境相对友好了）。
有时候是 uv python install 依赖的运行时下载不下来，因为它直连 uv 的 GitHub Release。这一点很重要，因为很多人已经放弃直接去 python.org 下载官方构建了，uv 这一套实在是太方便了。一台裸机配 python 环境，只需要一个 uv 和一些命令行，天然适合 AI Agent。
有时候是 uv add、uv sync、uv pip install 背后的 PyPI 访问出问题，哪怕你已经换了清华源等国内镜像。
这些问题让希望用 uv 减少配 python 环境时候的烦恼的用户感觉一朝回到解放前，如果你将 uv 推荐给你的朋友们，而他们恰巧又是在国内的网络环境下，他们甚至会怀疑是你的眼光有问题（这也是我的真实体验
对于我自己来说，当我需要讲一些公开培训课的时候，我需要统一给在场用户安装 python 环境，而我又不可能统一给在场用户安装**……于是 uv-custom 的国内环境安装脚本和 python build 镜像就很有价值了。
这就是 uv-custom 想解决的问题。
一个更贴近官方体验的大陆入口
uv-custom 是一个面向中国大陆的 uv 公益镜像入口。
这个项目没有重新发明一套安装方式，相反，这个项目的实现尽量做到了最小改动和克制：
尽量保持 uv 官方使用方式不变，只把最容易出问题的下载链路，换成更适合中国大陆网络环境的入口。
这个项目做了什么
uv-custom 主要做了四件事：
- 同步官方 uv release 的二进制本体 和 installer 脚本
- 同步 uv python install 需要的 python 运行时 Github Release 资产
- 提供一个统一的大陆可用安装入口（小文件如脚本等，走 CF worker，大文件走 S3 直连）
- 提供一个适合 uv / pip 使用的 PyPI Simple 代理入口（避免出现 pip 已经换源但 uv add 等等需要 simple 和 *.metadata 等清华源之类的镜像都没有镜像到的情况）
因此，uv-custom 解决是一整条实际使用链路：
从第一次安装 uv，到安装 Python 运行时，再到后续 add、lock、sync、pip install 时访问包索引和文件下载，这些环节都尽量接到国内可直接访问的稳定入口上。
它稳定吗？
我觉得还可以，因为有两点保证：
1. 不硬改官方安装器，而是尽量复用官方路径
项目提供的大陆可用的安装入口，并不是自己重写一整套安装逻辑，而是尽量复用官方 installer，再通过环境变量和配置，把后续下载来源切到镜像，做到最小改动，后续也好维护。
Github Action 固定轮询 uv 官方仓库，有新 release 就同步过去，目前看 CI 是一片绿的，看着就挺稳的（
image2300×1518 277 KB
2. 够重的 smoke test
由于有真实的用户拿着鞭子抽 （不是），这个项目的 smoke test 设计的时候非常重视“真实链路能不能跑通”，不只停留在函数级测试。
我在 Github 的 CI 上写了一个 smoke_matrix ，它会在 Linux、macOS、Windows 上清空环境后真实安装 uv、检查 profile 和 uv.toml、再跑一轮重依赖安装；uv_smoke.py 甚至故意把依赖拆成多次 uv add，还单独拉一次 torch 这种大包，尽量模拟真正的初始安装环境。
另外我也在我自己的上海 Ubuntu 服务器上进行了真实的联调测试（由 Agent 代劳），同样通过。
顺便我还拿我的学员们当做小白鼠 （不是） 做了线下的真实联调测试，效果很好。
它适合哪些人
如果你属于下面几类用户，我觉得这个项目应该会有帮助：
- 不得不在中国大陆使用 uv 的开发者
- 需要更稳定完成 uv python install 的用户
- 经常使用 uv add、uv sync、uv pip install，踩过坑的用户
- 想给企业国内网络环境下的团队提供一个更统一、更省心的 uv 接入方式的用户
如何使用
macOS / Linux
curl -LsSf https://uv.agentsmirror.com/install-cn.sh | sh
Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://uv.agentsmirror.com/install-cn.ps1 | iex"
安装完成后，它会把后续相关配置也接好，让 uv 本体安装、Python 运行时下载，以及默认的 PyPI 访问（清华源）都走更适合大陆环境的入口。
最后
本人承诺本项目完全开源，遵守 MIT LICENSE，不会有任何盈利的性质。如果遇到 S3 不稳定、域名过期等问题，会及时进行处理，切到备份方案等。
希望各位佬友指出本项目存在的不足，也欢迎 issue 和 pr，如有帮助，也希望能动动小手点个 star。如果有更多的需求，也欢迎在 issue 中提出来，感谢！
Github 仓库地址：
GitHub - Wangnov/uv-custom: 一个 uv 公益镜像，提供国内的 uv 和 uv python runtime 高速下载
一个 uv 公益镜像，提供国内的 uv 和 uv python runtime 高速下载
网友解答：--【壹】--：
这个我晓得，好几年前找到过的唯一一家，到目前为止可能也是唯一一家做了 python build 的镜像了吧，不过当时我用的时候发现版本不全，后面就没有再继续用。
--【贰】--：
uv 配置镜像源不也挺方便的吗，每次在 toml 里面加上就好了
--【叁】--：
toml里面配置的是pip/uv add的源，uv安装python版本的话还是从github上面拉的
--【肆】--：
感谢提醒，我找找看，如果有的话切过去兜底
--【伍】--：
看到torch了
首先国内镜像站 默认路径（版本）是 cu126
不同的特定版本 好像阿里开源站有个专门的wheel站 这块用的少不属性
其次 uv官方专门有个页面讲了不同的extra 对应不同的torch 方便打包
--【陆】--： Wangnov:
Wangnov:
- 不硬改官方安装器，而是尽量复用官方路径
- 够重的 smoke test
我感觉我废了，看谁的大段文章都感觉是GPT写的
不过还是得支持一下
--【柒】--：
NJU Mirror
用手机搜了下
uv也有官方镜像 Using uv in Docker | uv
一般我会打镜像会copy from 复制到 user/local/bin 下使用再配合国内源安装python运行环境
--【捌】--：
用了好久了我 基本上服务器 电脑我都装的佬的
我说最近咋没有发行版原来是搞大事情去了 佬牛牛
--【玖】--：
这个配置的不止是 pip 镜像源的，pip 确实不麻烦
--【拾】--：
uv python install 国内有镜像源
嗯 具体地址不记得 清华源的右下角 有个联合搜索 进去搜
--【拾壹】--：
支持一下。我个人每次都是直接开TUN模式，所有的命令就都没有问题了，也不需要配置镜像。
--【拾贰】--：
有空试试看，之前用uv安装torch，虽然设置了镜像还是有点慢，看看佬的好不好使
--【拾叁】--：
佬造福于大家！！！虽然暂时用不到，但是收藏了，难保以后。现在越来越收紧了。
--【拾肆】--：
大概是因为我天天用 GPT，所以被它带坏了语言习惯。不用怀疑，确实是手写的。请把不是而是还给人类
--【拾伍】--：
感谢大佬，突然就想到我的那个空闲存储可以用来做什么了。
--【拾陆】--：
确实，我也是只发现仅此一家。不过现在我也把它镜像了，就有二家了哈哈哈（虽然我只镜像了最新版，但是矩阵是全的）
--【拾柒】--：
去年有段时间版本更新不及时 但好像一般ARM和x86都有 最近几个月感觉还不错
国内独此一家 我也找遍了
为了打镜像 试过修改元数据yaml文件绕过去
最后还是自己打个包含常用python版本的镜像自用
后面恢复了就直接用了