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 中执行：

2. powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

复制代码

macOS 或 Linux 用户使用 curl：

2. curl -LsSf https://astral.sh/uv/install.sh | sh

复制代码

如果没有 curl，可以改用 wget：

2. wget -qO- https://astral.sh/uv/install.sh | sh

复制代码

需要安装特定版本时，在 URL 中指定版本号即可。例如安装 0.11.2：

2. # macOS/Linux
3. curl -LsSf https://astral.sh/uv/0.11.2/install.sh | sh
5. # Windows PowerShell
6. powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/0.11.2/install.ps1 | iex"

复制代码

### 系统包管理器安装

如果本机已有 Homebrew、Winget 或 Conda，也可以直接用包管理器安装：

2. # macOS
3. brew install uv
5. # Windows
6. winget install --id Astral.uv
8. # Linux / Conda
9. conda install -c conda-forge uv

复制代码

### pip / pipx 安装

已经安装 Python 的环境，可以通过 pip 安装，但更推荐使用 pipx 将 UV 隔离安装，避免污染全局 Python 环境：

2. pip install uv
4. # 或
5. pipx install uv

复制代码

## 验证安装

安装完成后需要关闭并重新打开终端，然后执行下面的命令确认版本：

2. uv --version
3. # 或
4. uv -V

复制代码

正常输出类似：

2. uv 0.11.13 (4512a3931 2026-05-10 x86_64-pc-windows-msvc)

复制代码

如果提示“command not found: uv”，说明 PATH 没有正确加载，可参考下文“常见问题”。

## 国内镜像加速配置（必做）

UV 默认从 PyPI 官方源下载包，国内网络环境下速度不稳定，建议配置清华镜像。镜像配置分为全局环境变量和项目级配置两种。

### 全局环境变量配置（推荐）

临时生效可在当前终端直接设置：

2. # Windows PowerShell 临时生效
3. $env:UV_INDEX_URL="https://pypi.tuna.tsinghua.edu.cn/simple"
4. $env:UV_PYTHON_DOWNLOAD_MIRROR="https://mirrors.tuna.tsinghua.edu.cn/python"
6. # macOS/Linux 临时生效
7. export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
8. export UV_PYTHON_DOWNLOAD_MIRROR=https://mirrors.tuna.tsinghua.edu.cn/python

复制代码

永久生效时，Windows 用户需要在“此电脑”->“属性”->“高级系统设置”->“环境变量”里，把上述两个变量加到用户变量中。macOS/Linux 用户将两行 export 命令追加到 ~/.zshrc 或 ~/.bashrc 末尾，然后执行 source ~/.zshrc 或 source ~/.bashrc。

验证环境变量是否加载：

2. # 检查包镜像配置
3. echo $env:UV_INDEX_URL
5. # 检查 Python 下载镜像配置
6. echo $env:UV_PYTHON_DOWNLOAD_MIRROR

复制代码

### 项目级配置

在项目根目录创建 uv.toml 文件，加入以下内容，即可让当前项目独立使用镜像：

2. index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
3. python-download-mirror = "https://mirrors.tuna.tsinghua.edu.cn/python"

复制代码

## 基本使用入门

### 管理 Python 版本

UV 可以自动下载安装 Python，无需手动到官网找安装包：

2. # 安装最新稳定版
3. uv python install
5. # 安装指定版本
6. uv python install 3.12
8. # 查看已安装的 Python 版本
9. uv python list

复制代码

### 创建项目和虚拟环境

初始化新项目时，UV 会自动创建虚拟环境：

2. uv init my_project
3. cd my_project

复制代码

如果已有项目，只需要在项目根目录手动创建虚拟环境：

2. uv venv

复制代码

### 依赖管理

UV 使用 pyproject.toml 和 uv.lock 管理依赖，常用命令如下：

2. # 添加依赖
3. uv add requests
4. uv add "fastapi>=0.110.0"
6. # 添加开发依赖
7. uv add pytest --dev
9. # 删除依赖
10. uv remove requests
12. # 按锁定文件同步依赖
13. uv sync
15. # 升级所有依赖到最新版本
16. uv lock --upgrade

复制代码

### 运行命令

不需要手动激活虚拟环境，uv run 会直接在当前项目环境里执行命令：

2. uv run python main.py

复制代码

也可以直接运行项目内注册的脚本：

2. uv run script_name

复制代码

## 常见问题与解决方案

### command not found: uv

原因通常是安装后没有重启终端，或者 ~/.local/bin 不在 PATH 中。检查安装路径：

- Windows：C:\Users\<你的用户名>\.local\bin
- macOS/Linux：~/.local/bin

临时添加到 PATH：

2. # macOS/Linux
3. export PATH=$PATH:~/.local/bin
5. # Windows PowerShell
6. $env:PATH += ";$env:USERPROFILE\.local\bin"

复制代码

### 下载速度慢或超时

配置清华源即可解决，参考上文“国内镜像加速配置”。

### 权限错误

Windows 下以管理员身份运行 PowerShell；macOS/Linux 下不要使用 sudo，UV 默认安装到用户目录，不需要 root 权限。

### 更新 UV

使用官方独立脚本安装的版本，直接执行：

2. uv self update

复制代码

## 卸载 UV

根据安装方式选择对应的卸载命令。

官方独立脚本安装：

2. # macOS/Linux
3. rm -rf ~/.local/bin/uv ~/.local/share/uv
5. # Windows PowerShell
6. Remove-Item -Recurse -Force "$env:USERPROFILE\.local\bin\uv.exe"
7. Remove-Item -Recurse -Force "$env:USERPROFILE\.local\share\uv"

复制代码

包管理器安装：

2. # Homebrew
3. brew uninstall uv
5. # Winget
6. winget uninstall --id Astral.uv
8. # pip
9. pip uninstall uv
11. # pipx
12. pipx uninstall uv

复制代码

## 总结

UV 的核心价值在于把 Python 版本管理、虚拟环境和依赖管理统一到一个快速命令中，配合清华镜像后在国内开发场景下体验更佳。建议新项目优先使用 uv init + uv add + uv run 的工作流。后续还可以继续探索 uv build、uv publish 等打包发布功能，但本文覆盖的安装、镜像配置和基础命令已经足够支撑日常开发。

热心网友3

感谢分享，教程写得很全面，尤其是国内镜像那块，对小白来说太有用了。之前装 uv 总是卡在下载和 PATH 上，按这个排查方法应该能省不少事。另外提一个小点，如果用的是 zsh，记得 export 之后 source 一下，不然容易以为没生效。整体很实用，收藏了！

热心网友3

感谢楼主分享！国内镜像那部分太实用了，之前用pip换源总是各种麻烦，UV直接通过环境变量配置确实方便不少。正好最近打算试试Rust生态的这些工具，收藏了慢慢看。

热心网友3

楼主整理得很详细，正好最近在折腾 UV，照着设置清华镜像后下载速度快多了，之前一直卡在 PyPI 上。补充一个小问题：如果以前装过旧版 UV，升级后用 `uv python list` 可能看不到新下载的版本，把 `~/.local/share/uv` 或 Windows 下的对应目录清一下再同步就好了。另外 `uv run` 确实省心，不用来回 activate。