概述
UV 是由 Astral 团队开发的高性能 Python 包管理器和解析器,旨在提供比传统工具更快的依赖解析和安装体验。本文档提供 UV 的安装指南及国内镜像源配置方法。
系统要求
- 支持的操作系统:Windows 10+/macOS 10.15+/Linux (glibc 2.31+)
- Python 版本:无需预先安装 Python(UV 自带 Python 环境管理)
安装方法
推荐方案:使用官方安装脚本
Linux/macOS 系统
base
# 执行一键安装脚本
curl -LsSf https://astral.sh/uv/install.sh | sh
Windows 系统
PowerShell
# PowerShell 中执行安装命令
irm https://astral.sh/uv/install.ps1 | iex
安装完成后,重启终端并验证安装:
bash
uv --version
备选方案:通过 Pipx 安装
bash
# 安装 pipx(如尚未安装)
python -m pip install --user pipx
python -m pipx ensurepath
# 通过 pipx 安装 uv
pipx install uv
镜像源配置
临时使用镜像源
通过环境变量临时指定镜像源(仅当前会话有效):
bash
# 使用阿里云镜像源
export UV_INDEX_URL="https://mirrors.aliyun.com/pypi/simple/"
# 或使用清华大学镜像源
export UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple/"
# 安装包(将使用上述镜像源)
uv pip install <package-name>
永久配置镜像源
配置文件路径
- Linux/macOS:
~/.config/uv/uv.toml
- Windows:
%APPDATA%\uv\uv.toml
配置内容
创建或编辑配置文件,添加以下内容:
toml
[index]
# 阿里云镜像源
url = "https://mirrors.aliyun.com/pypi/simple/"
# 或使用清华大学镜像源
# url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
命令行直接指定镜像源
bash
# 安装包时直接指定镜像源
uv pip install -i https://pypi.tuna.tsinghua.edu.cn/simple/ <package-name>
镜像源列表
提供商 | 镜像源地址 |
---|---|
阿里云 | mirrors.aliyun.com/pypi/simple... |
清华大学 | pypi.tuna.tsinghua.edu.cn/simple/ |
豆瓣 | pypi.doubanio.com/simple/ |
华为云 | repo.huaweicloud.com/repository/... |
配置验证与故障排除
验证配置
bash
# 检查当前生效的索引URL
uv config get index.url
# 测试包安装速度
uv pip install numpy
常见问题处理
-
SSL 证书错误
- 确保使用
https://
前缀而非http://
- 确保使用
-
配置未生效
- 验证配置文件路径和格式是否正确
- 使用
uv config list
查看所有配置
-
清除缓存
bashuv clean
注意事项
-
UV 的配置独立于 pip,需单独设置镜像源
-
不同项目的虚拟环境可以单独配置不同的源
-
定期更新 UV 工具以获取最新功能和安全更新:
bashuv self update
性能优化建议
- 选择地理位置最近的镜像源
- 定期清理缓存:
uv clean
- 对于大型项目,考虑使用 UV 的离线模式
通过以上配置,可显著提升在中国大陆地区的包下载速度,改善开发体验。