Python UV 完整安装教程

UV 是由 Astral 公司（Ruff 代码检查工具的开发者）用 Rust 编写的超快速 Python 包管理器和项目管理工具，速度比 pip 快 10-100 倍，可一站式替代 pip、pip-tools、virtualenv 和 pyenv 等多个工具。

一、系统要求

操作系统：Windows 10+、macOS 11+、Linux（x86_64/ARM64）
无需预先安装 Python（UV 可自动下载管理 Python 版本）

二、安装方法

方法一：官方独立安装脚本（推荐）

这是最推荐的安装方式，无需依赖任何现有环境，自动配置环境变量。

Windows（PowerShell）

复制代码

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

macOS/Linux（终端）

复制代码

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

如果系统没有 curl，可以使用 wget：

复制代码

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

安装特定版本

复制代码

# 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"

方法二：系统包管理器

macOS（Homebrew）

复制代码

brew install uv

Windows（Winget）

复制代码

winget install --id Astral.uv

Linux（Conda）

复制代码

conda install -c conda-forge uv

方法三：通过 pip 安装（已安装 Python 时）

复制代码

# 普通安装
pip install uv

# 推荐使用 pipx 安装到隔离环境
pipx install uv

三、验证安装

安装完成后，必须关闭并重新打开终端，然后运行以下命令验证：

复制代码

uv --version
# 或
uv -V

成功输出示例：

复制代码

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

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

由于默认源在国外，国内用户必须配置镜像才能获得良好的下载体验。

方法一：全局环境变量配置（推荐）

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 ：将上述两行添加到 ~/.zshrc 或 ~/.bashrc 文件末尾，然后执行 source ~/.zshrc

✅ 验证配置是否生效

在新终端中运行以下命令，检查环境变量是否已加载：

复制代码

# 检查包镜像配置
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"

五、基本使用入门

1. 安装 Python 版本

复制代码

# 安装最新稳定版 Python
uv python install

# 安装指定版本
uv python install 3.12

# 查看已安装的 Python 版本
uv python list

2. 创建新项目

复制代码

# 初始化新项目（自动创建虚拟环境）
uv init my_project
cd my_project

# 或在现有项目中创建虚拟环境
uv venv

3. 依赖管理

复制代码

# 添加依赖
uv add requests
uv add "fastapi>=0.110.0"
uv add pytest --dev  # 添加开发依赖

# 删除依赖
uv remove requests

# 同步依赖（根据 pyproject.toml 和 uv.lock 安装）
uv sync

# 更新所有依赖到最新版本
uv lock --upgrade

4. 运行命令

复制代码

# 在虚拟环境中运行 Python 脚本
uv run python main.py

# 运行项目中的脚本
uv run script_name

六、常见问题与解决方案

问题 1：安装后提示 "command not found: uv"

原因：环境变量未生效或未正确配置。

解决方案：

关闭并重新打开终端
检查安装路径是否在 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"

问题 2：下载速度慢或超时

解决方案：按照上文 "国内镜像加速配置" 部分配置清华源。

问题 3：权限错误

解决方案：

Windows：以管理员身份运行 PowerShell
macOS/Linux：不要使用 sudo，UV 会自动安装到用户目录

问题 4：更新 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