【笔记】加速 uv 安装:系统环境变量配置国内镜像源

发布于:2025-07-31 ⋅ 阅读:(17) ⋅ 点赞:(0)

使用 Conda 工具链创建 UV 本地虚拟环境全记录——基于《Python 多版本与开发环境治理架构设计》-CSDN博客

命令行创建 UV 环境及本地化实战演示—— 基于《Python 多版本与开发环境治理架构设计》的最佳实践-CSDN博客


 

 

 


加速 uv 包安装:Windows 系统环境变量配置国内镜像源

一、为什么要配置环境变量加速 uv

uv 作为高效 Python 包管理工具,默认从官方 PyPI 源(Simple index)拉取依赖。受国内网络环境影响,常出现下载慢、连接不稳定问题。

通过配置系统环境变量 UV_DEFAULT_INDEX,将依赖源替换为国内镜像(如清华镜像),让 uv 从更近的服务器拉取包,大幅提升安装效率,告别 “龟速” 等待!


 

 

 


二、Windows 系统配置步骤

(一)打开系统环境变量设置界面

  1. 右键点击 **“此电脑”(或 “我的电脑”)→ 选择“属性”**。
  2. 在弹出的 “关于” 窗口中,点击左侧 **“高级系统设置”**。
  3. 在 “系统属性” 窗口的 **“高级”标签页下,点击“环境变量”** 按钮,进入配置界面。

(二)新建系统环境变量

  1. 在 “环境变量” 窗口中,找到 **“系统变量”区域(影响全局环境;若仅需当前用户生效,可选 “用户变量”)→ 点击“新建”**。
  2. 在 “新建系统变量” 对话框中:
    • 变量名(N):输入 UV_DEFAULT_INDEX(严格区分大小写,需完全一致)。
UV_DEFAULT_INDEX
    • 变量值(V):填入国内镜像源地址,推荐清华 PyPI 镜像(稳定常用):
https://pypi.tuna.tsinghua.edu.cn/simple

也可按需替换为其他源(如阿里云镜像 Simple Index)。

    • 填写完成后点击 **“确定”** 保存。
  • 依次点击 “环境变量” 窗口、“系统属性” 窗口的 **“确定”**,完成设置。

 

(三)让环境变量生效

配置后,关闭当前所有终端窗口(如 CMD、PowerShell 等),重新打开新终端。新终端会自动加载最新环境变量,配置即可生效。


 

 

 


三、验证配置(适配低版本 uv)

若 uv 版本较低(不支持 config 子命令),可通过实际安装测试验证:

  1. 打开终端,进入 Python 项目虚拟环境(如项目的 .venv 环境,若有)。
  2. 执行 uv pip install 安装任意包(以 requests 为例):
  3. uv pip install requests
  4. 观察安装过程:
    • 若下载速度明显加快(对比未配置前),或终端显示从 Simple Index 拉取包,说明配置生效。

 

 

 


四、其他国内镜像源与灵活用法

(一)更多国内镜像源推荐

除清华镜像,可按需替换为以下源:

https://mirrors.aliyun.com/pypi/simple/
https://mirrors.cloud.tencent.com/pypi/simple

 

(二)临时切换镜像源(无需修改环境变量)

若需临时换源(不影响系统配置),可在终端执行:

Windows 系统临时设置
set UV_DEFAULT_INDEX=https://mirrors.aliyun.com/pypi/simple/
安装时直接指定源

也可在安装包时,通过 --default-index 参数临时指定镜像:

uv pip install <包名> --default-index https://pypi.tuna.tsinghua.edu.cn/simple

 

 

 


五、常见问题及解决

(一)配置后不生效

  1. 检查环境变量名称 / 值:确认 UV_DEFAULT_INDEX 无拼写错误,变量值无多余空格。
  2. 重启终端:确保关闭旧终端,重新打开新终端加载最新配置。

(二)镜像源访问异常

  1. 换源测试:尝试切换其他国内镜像(如清华→阿里云),排除单个源的网络问题。
  2. 网络验证:浏览器访问镜像源地址(如 Simple Index),若能打开并看到包索引,说明源可访问。

通过配置系统环境变量,让 uv 借助国内镜像源加速依赖安装,开发效率直接拉满!赶紧动手试试,告别漫长等待~


网站公告

今日签到

点亮在社区的每一天
去签到