3
0
0

uv 使用与国内加速教程

2026-09-20
2026-09-20
文章摘要
|

#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-url
    • UV_PYTHON_INSTALL_MIRROR、UV_PYPY_INSTALL_MIRROR、UV_PYTHON_DOWNLOADS_JSON_URL
    • UV_INSTALLER_GITHUB_BASE_URL
    • UV_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,只需三步即可回到官方默认行为:

  1. 删除 shell profile 中的受管块(~/.bashrc、~/.zshrc、~/.profile 或 Windows 的 $PROFILE 中,# >>> uv mirror managed block >>> 到 # <<< uv mirror managed block <<< 之间的内容)
  2. 恢复或清理 uv.toml:删除 python-downloads-json-url、python-install-mirror、pypy-install-mirror 等键,或直接用安装时生成的备份文件覆盖
  3. 清理手动设置过的环境变量: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
  • 参考链接:
  1. Astral/uv官方文档 : https://docs.astral.sh/uv/
  2. 一个面向中国大陆的uv公益镜像入口:uv-custom : https://github.com/Wangnov/uv-custom

如果本文对你有帮助,欢迎点赞、在看、转发,让更多开发、运维同学们看到!

支持与分享

如果这篇文章对你有帮助,欢迎分享给更多人或者给予支持!

uv 使用与国内加速教程
/archives/uv-shi-yong-yu-guo-nei-jia-su-jiao-cheng
Author
Administrator
Published at
2026-09-20

欢迎来到我的博客!