uv 配置清华镜像源完整指南（Windows）

uv 配置清华镜像源完整指南Windows uv 是用 Rust 编写的超快 Python 包管理工具速度比 pip 快 10-100 倍。本文记录在 Windows 环境下安装 uv 并配置清华镜像源的完整过程以及踩坑经验。---目录- [一、安装 uv]- [二、配置清华镜像源]- [三、验证配置是否生效]- [四、使用 uv 管理虚拟环境和依赖]- [五、常见问题与解决方案]- [六、常用命令速查表]---一、安装 uv1.1 安装powershell# 方式一使用 py 启动器py -m pip install uv# 方式二指定 Python 路径D:\Develop\Python 3.11.9\python.exe -m pip install uv1.2 验证安装powershelluv --version# 输出示例uv 0.11.25 (1fc7de7c4 2026-06-26 x86_64-pc-windows-msvc)---二、配置清华镜像源默认情况下uv 使用 PyPI 官方源海外服务器国内下载速度很慢。配置清华镜像源后下载速度可提升 5-10 倍。2.1 修改配置文件推荐配置文件位置| 系统 | 路径 ||------|------|| Windows | %APPDATA%\uv\uv.toml即 C:\Users\用户名\AppData\Roaming\uv\uv.toml在 PowerShell 中执行以下命令写入配置powershell中1. 确保目录存在New-Item -ItemType Directory -Force -Path $env:APPDATA\uv- 目录 不存在 → 自动创建- 目录 已存在 → 不报错静默跳过2. 写入配置内容直接在 PowerShell 中执行[pip]index-url https://pypi.tuna.tsinghua.edu.cn/simple | Out-File -FilePath $env:APPDATA\uv\uv.toml -Encoding utf8 -Force写入后配置文件 uv.toml 的完整内容为toml[pip]index-url https://pypi.tuna.tsinghua.edu.cn/simple三、验证配置是否生效powershell第一步清除旧缓存uv cache clean第二步验证请求是否走清华源找一个位置新建一个虚拟环境uv venvuv pip install flask --dry-run -v 21 | Select-String tuna如果输出中出现以下内容说明配置成功DEBUG Sending fresh GET request for: https://pypi.tuna.tsinghua.edu.cn/simple/flask/DEBUG Sending fresh GET request for: https://pypi.tuna.tsinghua.edu.cn/simple/blinker/DEBUG Sending fresh GET request for: https://pypi.tuna.tsinghua.edu.cn/simple/click/...四、使用 uv 管理虚拟环境和依赖4.1 创建虚拟环境powershell在当前目录创建 .venv默认名称uv venv指定 Python 版本uv venv --python D:\Develop\Python 3.11.9\python.exe指定环境名称uv venv myenv4.2 安装依赖powershell从 requirements.txt 安装uv pip install -r .\requirements.txt安装单个包uv pip install flask安装多个包uv pip install flask requests pandas4.3 为多个项目分别创建独立环境powershell项目 Acd D:\projects\project-auv venvuv pip install -r .\requirements.txt项目 Bcd D:\projects\project-buv venvuv pip install -r .\requirements.txt每个项目的 .venv 完全独立互不干扰。---五、常见问题与解决方案问题 1uv 命令找不到**报错信息**无法将uv项识别为 cmdlet、函数、脚本文件或可运行程序的名称**原因**Python 的 Scripts 目录不在系统 PATH 中。**解决方案**1.永久解决推荐将 D:\Develop\Python 3.11.9\Scripts 添加到系统环境变量 PATH。2.临时解决powershell# 临时加入 PATH当前终端有效$env:PATH ;D:\Develop\Python 3.11.9\Scripts# 或使用完整路径调用 D:\Develop\Python 3.11.9\Scripts\uv.exe --version---问题 2配置了清华源但不生效仍访问 pypi.org**现象**uv pip install -v 的输出中仍然显示访问 https://pypi.org/simple/。**原因**配置文件有问题配置文件中使用了 [[index]] 格式uv config 自动生成多个 index 条目冲突。**解决方案**用 [pip] 格式重写配置文件powershell[pip]index-url https://pypi.tuna.tsinghua.edu.cn/simple | Out-File -FilePath $env:APPDATA\uv\uv.toml -Encoding utf8 -Force# 清除缓存后重试uv cache clean---问题 3下载速度慢**现象**Prepared xxx packages in 50 s安装阶段很快但下载阶段很慢。**原因**默认使用 PyPI 官方源国内访问慢。**解决方案**配置清华源见第二节。配置前后对比| 指标 | 配置前pypi.org | 配置后清华源 ||------|-------------------|-----------------|| 57 个包下载耗时 | 约 53 秒 | 约 5-10 秒 || 57 个包安装耗时 | 约 4 秒 | 约 4 秒 |---六、常用命令速查表| 功能 | 命令 ||------|------|| 创建虚拟环境 | uv venv || 指定 Python 创建环境 | uv venv --python 路径\python.exe || 从文件安装依赖 | uv pip install -r .\requirements.txt || 安装单个包 | uv pip install flask || 查看已安装包 | uv pip list || 卸载包 | uv pip uninstall flask || 清除缓存 | uv cache clean || 查看 uv 版本 | uv --version || 升级 uv | py -m pip install --upgrade uv |---七、总结uv 作为新一代 Python 包管理工具安装和使用都非常简单。对于国内用户最关键的一步就是配置清华镜像源可以显著提升下载速度。推荐使用配置文件方式uv.toml进行全局配置一劳永逸。