UV Python包管理器安装教程：国内镜像配置与常见问题
UV 是 Astral 公司用 Rust 开发的 Python 包管理工具，官方定位是替代 pip、pip-tools、virtualenv 和 pyenv 的“一站式”解决方案。在实测体验中，UV 的依赖解析和包安装速度明显优于传统 pip 工作流，尤其适合需要频繁创建虚拟环境、切换 Python 版本或管理多项目依赖的开发者。本文基于 UV 0.11.x 版本，整理完整的安装、镜像加速、基本使用和排错方法。## 系统要求与前置条件
UV 支持 Windows 10+、macOS 11+ 以及 Linux（x86_64 / ARM64）。它不要求系统预先安装 Python，因为 UV 自身可以自动下载并管理 Python 版本。这一点对刚接触 Python 环境管理的用户非常友好，可以避免手动配置 PATH 和版本冲突。
## 安装 UV 的三种方式
### 官方独立安装脚本（推荐）
官方脚本不依赖现有 Python 环境，安装后会自动配置用户级环境变量。Windows 用户可以在 PowerShell 中执行：
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
macOS 或 Linux 用户使用 curl：
curl -LsSf https://astral.sh/uv/install.sh | sh
如果没有 curl，可以改用 wget：
wget -qO- https://astral.sh/uv/install.sh | sh
需要安装特定版本时，在 URL 中指定版本号即可。例如安装 0.11.2：
# macOS/Linux
curl -LsSf https://astral.sh/uv/0.11.2/install.sh | sh
# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/0.11.2/install.ps1 | iex"
### 系统包管理器安装
如果本机已有 Homebrew、Winget 或 Conda，也可以直接用包管理器安装：
# macOS
brew install uv
# Windows
winget install --id Astral.uv
# Linux / Conda
conda install -c conda-forge uv
### pip / pipx 安装
已经安装 Python 的环境，可以通过 pip 安装，但更推荐使用 pipx 将 UV 隔离安装，避免污染全局 Python 环境：
pip install uv
# 或
pipx install uv
## 验证安装
安装完成后需要关闭并重新打开终端，然后执行下面的命令确认版本：
uv --version
# 或
uv -V
正常输出类似：
uv 0.11.13 (4512a3931 2026-05-10 x86_64-pc-windows-msvc)
如果提示“command not found: uv”，说明 PATH 没有正确加载，可参考下文“常见问题”。
## 国内镜像加速配置（必做）
UV 默认从 PyPI 官方源下载包，国内网络环境下速度不稳定，建议配置清华镜像。镜像配置分为全局环境变量和项目级配置两种。
### 全局环境变量配置（推荐）
临时生效可在当前终端直接设置：
# Windows PowerShell 临时生效
$env:UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"
$env:UV_PYTHON_DOWNLOAD_MIRROR="https://mirrors.tuna.tsinghua.edu.cn/python"
# macOS/Linux 临时生效
export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
export UV_PYTHON_DOWNLOAD_MIRROR=https://mirrors.tuna.tsinghua.edu.cn/python
永久生效时，Windows 用户需要在“此电脑”->“属性”->“高级系统设置”->“环境变量”里，把上述两个变量加到用户变量中。macOS/Linux 用户将两行 export 命令追加到 ~/.zshrc 或 ~/.bashrc 末尾，然后执行 source ~/.zshrc 或 source ~/.bashrc。
验证环境变量是否加载：
# 检查包镜像配置
echo $env:UV_INDEX_URL
# 检查 Python 下载镜像配置
echo $env:UV_PYTHON_DOWNLOAD_MIRROR
### 项目级配置
在项目根目录创建 uv.toml 文件，加入以下内容，即可让当前项目独立使用镜像：
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
python-download-mirror = "https://mirrors.tuna.tsinghua.edu.cn/python"
## 基本使用入门
### 管理 Python 版本
UV 可以自动下载安装 Python，无需手动到官网找安装包：
# 安装最新稳定版
uv python install
# 安装指定版本
uv python install 3.12
# 查看已安装的 Python 版本
uv python list
### 创建项目和虚拟环境
初始化新项目时，UV 会自动创建虚拟环境：
uv init my_project
cd my_project
如果已有项目，只需要在项目根目录手动创建虚拟环境：
uv venv
### 依赖管理
UV 使用 pyproject.toml 和 uv.lock 管理依赖，常用命令如下：
# 添加依赖
uv add requests
uv add "fastapi>=0.110.0"
# 添加开发依赖
uv add pytest --dev
# 删除依赖
uv remove requests
# 按锁定文件同步依赖
uv sync
# 升级所有依赖到最新版本
uv lock --upgrade
### 运行命令
不需要手动激活虚拟环境，uv run 会直接在当前项目环境里执行命令：
uv run python main.py
也可以直接运行项目内注册的脚本：
uv run script_name
## 常见问题与解决方案
### command not found: uv
原因通常是安装后没有重启终端，或者 ~/.local/bin 不在 PATH 中。检查安装路径：
- Windows：C:\Users\<你的用户名>\.local\bin
- macOS/Linux：~/.local/bin
临时添加到 PATH：
# macOS/Linux
export PATH=$PATH:~/.local/bin
# Windows PowerShell
$env:PATH += ";$env:USERPROFILE\.local\bin"
### 下载速度慢或超时
配置清华源即可解决，参考上文“国内镜像加速配置”。
### 权限错误
Windows 下以管理员身份运行 PowerShell；macOS/Linux 下不要使用 sudo，UV 默认安装到用户目录，不需要 root 权限。
### 更新 UV
使用官方独立脚本安装的版本，直接执行：
uv self update
## 卸载 UV
根据安装方式选择对应的卸载命令。
官方独立脚本安装：
# macOS/Linux
rm -rf ~/.local/bin/uv ~/.local/share/uv
# Windows PowerShell
Remove-Item -Recurse -Force "$env:USERPROFILE\.local\bin\uv.exe"
Remove-Item -Recurse -Force "$env:USERPROFILE\.local\share\uv"
包管理器安装：
# Homebrew
brew uninstall uv
# Winget
winget uninstall --id Astral.uv
# pip
pip uninstall uv
# pipx
pipx uninstall uv
## 总结
UV 的核心价值在于把 Python 版本管理、虚拟环境和依赖管理统一到一个快速命令中，配合清华镜像后在国内开发场景下体验更佳。建议新项目优先使用 uv init + uv add + uv run 的工作流。后续还可以继续探索 uv build、uv publish 等打包发布功能，但本文覆盖的安装、镜像配置和基础命令已经足够支撑日常开发。
Re: UV Python包管理器安装教程：国内镜像配置与常见问题
感谢分享，教程写得很全面，尤其是国内镜像那块，对小白来说太有用了。之前装 uv 总是卡在下载和 PATH 上，按这个排查方法应该能省不少事。另外提一个小点，如果用的是 zsh，记得 export 之后 source 一下，不然容易以为没生效。整体很实用，收藏了！Re: UV Python包管理器安装教程：国内镜像配置与常见问题
感谢楼主分享！国内镜像那部分太实用了，之前用pip换源总是各种麻烦，UV直接通过环境变量配置确实方便不少。正好最近打算试试Rust生态的这些工具，收藏了慢慢看。Re: UV Python包管理器安装教程：国内镜像配置与常见问题
楼主整理得很详细，正好最近在折腾 UV，照着设置清华镜像后下载速度快多了，之前一直卡在 PyPI 上。补充一个小问题：如果以前装过旧版 UV，升级后用 `uv python list` 可能看不到新下载的版本，把 `~/.local/share/uv` 或 Windows 下的对应目录清一下再同步就好了。另外 `uv run` 确实省心，不用来回 activate。
页:
[1]