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"

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

解决方案:

  1. 关闭并重新打开终端

  2. 检查安装路径是否在 PATH 中:

    • Windows:C:\Users\<你的用户名>\.local\bin
    • macOS/Linux:~/.local/bin
  3. 手动添加到 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
相关推荐
LiaoWL123几秒前
从零搭一个 RAG 知识库(二):换上语义 Embedding——BGE 实测与阈值重校准
python·大模型·numpy·embedding·向量检索·rag
Dmz丶17 分钟前
前端转 AI 100 天 Day 48:向量数据库——100 万向量的毫秒级检索
python
青少儿编程课堂24 分钟前
蓝桥杯·全国青少年信息素养大赛·电子学会Python/C++考级:中国剩余定理解析
c++·python·算法·bfs·信息学竞赛
wuxianda10301 小时前
Swift 项目用 Xcode 脚手架起步:默认工程结构和依赖组合为什么会被识别成同源
开发语言·xcode·swift·4.3a·appstore审核
菜鸟~noob2331 小时前
[AI]间章:系列走到这里,聊聊后面的规划、造卡需要的软件平台,以及为什么我要先暂停更新
人工智能·python·fpga开发·django·pygame
ShineWinsu1 小时前
对于Qt:QVBoxLayout常见属性以及方法的解析
开发语言·数据库·c++·qt·gui·客户端·布局管理器
Sarvartha2 小时前
反射综合案例:SQL 语句生成
java·开发语言
TomEval11 小时前
【测AI】第26篇:线上模型监控与告警体系 — 测试不是终点
人工智能·python·功能测试·ai
prince_zxill11 小时前
PEP 751 pylock.toml 实测:pip 26.3 装 6 个包版本全钉死,但 [web] 选不中任何东西
python·pip·依赖管理·pep 751
ShineWinsu13 小时前
对于Qt:QFormLayout常见属性以及方法的解析
开发语言·c++·qt·面试·客户端·表单·qformlayout