uv 使用与国内加速教程
#uv 使用与国内加速教程
uv 是 Astral 用 Rust 编写的极速 Python 包与项目管理工具,可以替代 pip、pip-tools、pipx、poetry、pyenv、virtualenv 等多个工具,速度比 pip 快 10-100 倍。国内直连官方源常常较慢,下面整理了安装、常用功能,以及两种国内加速方案(手动配置镜像 / 使用一键公益镜像项目 uv-custom)。
作者推荐直接使用方案二。
一、安装 uv
官方安装脚本
macOS / Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows (PowerShell):
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
用 pip 安装(适合已有 Python 环境,想顺手用国内源加速):
pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simple
验证安装:
uv --version
二、核心功能速览
1. 项目管理(类似 poetry / rye)
uv init example
cd example
uv add ruff # 添加依赖(自动建虚拟环境)
uv run ruff check # 在项目环境中运行命令
uv lock # 生成锁文件
uv sync # 按锁文件同步环境
2. 运行单文件脚本(支持内联依赖声明)
uv add --script example.py requests
uv run example.py
3. 工具管理(类似 pipx)
uvx pycowsay 'hello world!' # 临时环境运行工具
uv tool install ruff # 全局安装工具
4. Python 版本管理
uv python install 3.10 3.11 3.12
uv python pin 3.11
5. pip 兼容接口(迁移成本低)
uv venv
uv pip install -r requirements.txt
uv pip compile requirements.in -o requirements.txt
三、加速方案一:手动配置国内镜像
uv 慢主要卡在两处:PyPI 包索引 和 Python 解释器下载(python-build-standalone,托管在 GitHub Releases)。
1. 配置 PyPI 镜像源
临时使用:
uv pip install requests --index-url https://pypi.tuna.tsinghua.edu.cn/simple
环境变量(当前 shell 会话生效):
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple # Linux/macOS
set UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple # Windows
全局配置文件(一劳永逸):
- Linux/macOS:
~/.config/uv/uv.toml - Windows:
%APPDATA%\uv\uv.toml
[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"
default = true
单个项目配置则写入项目根目录的 uv.toml 或 pyproject.toml(后者需加 tool. 前缀:[[tool.uv.index]])。
常用国内镜像:
- 清华:
https://pypi.tuna.tsinghua.edu.cn/simple - 中科大:
https://mirrors.ustc.edu.cn/pypi/simple - 阿里云:
https://mirrors.aliyun.com/pypi/simple/ - 腾讯云:
https://mirrors.cloud.tencent.com/pypi/simple/
2. 配置 Python 解释器下载镜像
uv python install 默认从 GitHub Releases 拉取,国内直连常超时,可替换为代理镜像。
环境变量:
export UV_PYTHON_INSTALL_MIRROR="https://ghfast.top/https://github.com/astral-sh/python-build-standalone/releases/download"
或写入 uv.toml(需放在 [[index]] 段落之前):
python-install-mirror = "https://ghfast.top/https://github.com/astral-sh/python-build-standalone/releases/download"
3. 一键换源小工具(可选)
uvx cnpip set --uv # 自动测速选优,写入 ~/.config/uv/uv.toml
四、加速方案二:使用 uv-custom 公益镜像
Wangnov/uv-custom 是一个面向中国大陆的 uv 公益镜像项目,同步官方 uv release、Python 运行时资产,并提供 PyPI Simple 代理,目标是让整套官方使用方式在国内更稳定,而不是另起一套分发逻辑。
1. 一键安装(替代官方安装脚本)
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"
2. 安装脚本自动做了什么
install-cn 不会另起分发逻辑,而是复用官方安装路径:
- 直接分发官方
uv-installer.sh/uv-installer.ps1 - 通过
UV_INSTALLER_GITHUB_BASE_URL让官方 installer 改从镜像下载uv二进制本体 - 安装完成后自动写入
uv.toml与受管环境变量,包括:python-install-mirror、pypy-install-mirror、python-downloads-json-urlUV_PYTHON_INSTALL_MIRROR、UV_PYPY_INSTALL_MIRROR、UV_PYTHON_DOWNLOADS_JSON_URLUV_INSTALLER_GITHUB_BASE_URLUV_DEFAULT_INDEX(默认指向https://uv.agentsmirror.com/pypi/simple)
这些环境变量都只是默认值,如果你之前已手动设置过同名变量,镜像会让位,不需要额外清理。
其中 UV_DEFAULT_INDEX 指向的 PyPI 代理入口特点是:
simple页面和*.metadata由镜像自己代理缓存- wheel / sdist 包体优先走清华源,失败时自动回退官方
files.pythonhosted.org
如果本机已存在 uv.toml,脚本会先备份再更新受管键,不会破坏已有配置。
3. 只想单独换 Python 下载源
如果只想让 uv python install 走别的镜像(比如高校源),直接导出变量即可,不需要卸载整个 uv-custom 配置:
export UV_PYTHON_INSTALL_MIRROR="https://mirror.nju.edu.cn/github-release/astral-sh/python-build-standalone"
uv python install 3.12.13
4. 退出镜像 / 恢复官方设置
不需要卸载 uv,只需三步即可回到官方默认行为:
- 删除 shell profile 中的受管块(
~/.bashrc、~/.zshrc、~/.profile或 Windows 的$PROFILE中,# >>> uv mirror managed block >>>到# <<< uv mirror managed block <<<之间的内容) - 恢复或清理
uv.toml:删除python-downloads-json-url、python-install-mirror、pypy-install-mirror等键,或直接用安装时生成的备份文件覆盖 - 清理手动设置过的环境变量:
UV_INSTALLER_GITHUB_BASE_URL、UV_PYTHON_DOWNLOADS_JSON_URL、UV_PYTHON_INSTALL_MIRROR、UV_PYPY_INSTALL_MIRROR、UV_DEFAULT_INDEX
五、两种方案怎么选
| 方案 | 优点 | 适合场景 |
|---|---|---|
| 手动配置国内镜像(清华/中科大等) | 简单可控,不依赖第三方项目,镜像本身稳定性有大厂背书 | 只需要加速 PyPI 安装,不太在意 Python 解释器下载速度 |
| uv-custom 公益镜像 | 一条命令搞定 uv 本体、Python 运行时、PyPI 三处加速,且尽量复用官方安装逻辑,退出也方便 | 想要"装完就是官方体验但速度更快",尤其是常用 uv python install 下载解释器的场景 |
两者也可以叠加:用 uv-custom 的一键脚本装好 uv 和运行时加速,再按需把 UV_DEFAULT_INDEX 手动覆盖成自己更信任的 PyPI 镜像。
文档信息
- 文章作者:运维技术团队 - Devin
- 发布日期:2026-09-20
- 适用平台:linux、windows
- 参考链接:
- Astral/uv官方文档 : https://docs.astral.sh/uv/
- 一个面向中国大陆的uv公益镜像入口:uv-custom : https://github.com/Wangnov/uv-custom
如果本文对你有帮助,欢迎点赞、在看、转发,让更多开发、运维同学们看到!
