Python中uv安装、卸载与实战的完整教程

2026-09-17 08:30:12 作者：蜡台

uv 是 Astral 团队用Rust 编写的一体化 Python 开发工具,彻底重构了传统 Python 工具链的体验,下面我们就来看看如何在Python中安装、卸载uv并进行实战应用的吧

前言

uv 是 Astral 团队用Rust 编写的一体化 Python 开发工具，彻底重构了传统 Python 工具链的体验。它不只是一个包管理器，而是集 Python 版本管理、虚拟环境、依赖安装、项目初始化、脚本运行、依赖锁定 于一体的全能工具。

一、uv 优势与适用场景

相较于传统 Python 工具链，uv 核心优势：

速度碾压：依赖解析、安装、打包速度比 pip 快 10–100 倍，比 poetry 快数十倍
一站式全能：无需 venv、无需 pip、无需 pyenv、无需 poetry，一个工具搞定所有
零依赖轻量化：单二进制文件，绿色免安装、跨平台兼容
官方原生支持：自动托管多 Python 版本，环境隔离极致干净
兼容传统生态：完美兼容 requirements.txt、pyproject.toml，无缝迁移旧项目

二、多种安装方式

uv 提供多种安装方案，优先推荐官方独立脚本安装，无依赖、可自更新、稳定性最佳；Homebrew、包管理器为备选，pip 安装仅作兼容兜底。

2.1 Mac / Linux 安装

方案1：官方一键脚本

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

方案2：Homebrew 安装（Mac）

# 先更新brew索引，解决旧版本找不到uv的问题
brew update
brew install uv

方案3：pip 安装

pip install uv

2.2 Windows 安装（PowerShell 执行）

方案1：官方一键脚本

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

方案2：系统包管理器

# winget 安装
winget install --id=astral-sh.uv -e

# scoop 安装
scoop install main/uv

2.3 安装验证与更新

安装完成后重启终端，执行以下命令验证是否安装成功：

# 查看版本
uv --version
uvx --version

# 自更新（官方脚本安装专属）
uv self update

# brew安装更新方式
brew upgrade uv

三、uv 核心基础使用

掌握以下命令，即可替代 90% 的 pip、venv、pyenv 日常操作，适配绝大多数开发场景。

3.1 Python 版本管理 ---- 替代 pyenv

uv 可自动下载、托管多版本 Python，无需手动配置环境变量：

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

# 自动安装适配当前项目的Python版本
uv python install

# 安装指定版本Python（如3.11、3.12）
uv python install 3.11

# 查看当前使用的Python路径
uv python find
# 卸载指定托管版本
uv python uninstall 3.11

3.2 虚拟环境管理（替代 venv）

uv 虚拟环境创建速度远快于原生 venv，操作更简洁：

# 在当前目录创建.venv虚拟环境
uv venv

# 激活虚拟环境
# Mac/Linux
source .venv/bin/activate

# Windows PowerShell
.venv\Scripts\Activate.ps1

# 退出虚拟环境
deactivate

# 删除虚拟环境
rm -rf .venv

3.3 依赖包安装与管理（替代 pip）

完全兼容 pip 语法，速度碾压原生 pip，支持版本锁定、批量安装、升级：

# 安装最新版本包
uv install requests

# 安装指定版本包
uv install numpy==1.26.0

# 卸载包
uv uninstall requests

# 查看已安装依赖
uv list

# 升级所有依赖
uv upgrade

# 清空全局缓存（解决安装报错、缓存冲突）
uv cache clean

3.4 项目依赖锁定与还原（requirements.txt 双向适配）

自动生成、解析 requirements.txt，适配传统 Python 项目：

# 导出项目依赖到requirements.txt
uv pip freeze > requirements.txt

# 批量安装依赖
uv pip install -r requirements.txt

3.5 快速运行Python脚本

# 直接运行脚本，自动适配环境
uv run main.py

四、标准 uv 项目完整实战流程

从零搭建一个规范、可协作、可部署的 Python 项目，全程 uv 工具链：

# 1. 创建项目文件夹
mkdir uv-demo && cd uv-demo

# 2. 初始化uv项目（生成pyproject.toml配置文件）
uv init

# 3. 创建虚拟环境
uv venv

# 4. 激活环境并安装依赖
source .venv/bin/activate
# 安装依赖
uv install flask

# 5. 运行项目
uv run main.py

初始化后项目自动生成规范配置文件，依赖、环境统一管理，适配团队协作与项目部署。

五、临时关闭 uv（不卸载，可随时恢复）

若仅临时回归原生 pip 环境，无需卸载，仅关闭 uv 环境接管即可：

1.关闭终端所有 uv 相关进程，退出虚拟环境deactivate

2.注释掉 shell 配置中的 uv 环境变量

zsh：编辑 ~/.zshrc
bash：编辑 ~/.bash_profile

注释以下内容：

# export PATH="$HOME/.cargo/bin:$PATH"
# export PATH="$HOME/.local/bin:$PATH"

3.刷新终端配置

source ~/.zshrc

此时终端不再识别 uv 命令，完全使用原生 Python + pip 工具链，取消注释即可恢复使用。

六、零残留彻底卸载 uv

如需彻底移除 uv，需按清空数据→删除程序→清理环境变量→验证清理 流程操作，杜绝缓存、配置残留。

6.1 通用前置清理

优先关闭 uv 服务、清空所有托管数据：

# 清空全局缓存
uv cache clean

# 卸载所有uv托管的Python版本
uv python uninstall --all

# 删除uv工具目录、Python托管目录
rm -rf "$(uv python dir)"
rm -rf "$(uv tool dir)"

6.2 Mac / Linux 分场景卸载

场景1：官方脚本安装

# 删除主程序
rm -f ~/.local/bin/uv ~/.local/bin/uvx
rm -rf ~/.cargo/bin/uv ~/.cargo/bin/uvx

# 彻底清理残留目录
rm -rf ~/.cache/uv ~/.local/share/uv

场景2：Homebrew 安装

brew uninstall uv
brew autoremove

场景3：pip / pipx 安装

pip uninstall uv -y
pipx uninstall uv

6.3 Windows 彻底卸载（PowerShell）

# 前置清理
uv cache clean
uv python uninstall --all
Remove-Item -Recurse -Force "$(uv python dir)"
Remove-Item -Recurse -Force "$(uv tool dir)"

# 删除程序与残留目录
Remove-Item -Force "$env:USERPROFILE\.local\bin\uv.exe"
Remove-Item -Force "$env:USERPROFILE\.local\bin\uvx.exe"
Remove-Item -Recurse -Force "$env:LOCALAPPDATA%\uv"

6.4 终极清理：删除环境变量

删除配置文件中 uv 自动写入的 PATH 路径，避免终端自动复原：

Mac/Linux：编辑 shell 配置文件~/.zshrc / ~/.bash_profile，移除 uv 相关 export 语句，执行 source 配置文件 刷新

Windows：打开系统环境变量，删除 .local/bin 及 uv 相关路径，重启终端

6.5 卸载验证

重启终端，执行以下命令，提示 command not found 即为清理干净：

uv --version
which uv

七配置镜像

1. 全局配置

(1). 用户级

Linux/macOS请创建并编辑 ~/.config/uv/uv.toml或者$XDG_CONFIG_HOME/uv/uv.toml

Windows请创建并编辑 %APPDATA%\uv\uv.toml

(2). 系统级

Linux/macOS请创建并编辑 /etc/uv/uv.toml或者$XDG_CONFIG_DIRS/uv/uv.toml

Windows请创建并编辑 %SYSTEMDRIVE%\ProgramData\uv\uv.toml

uv.toml

# 1. CPython 代理配置（必须放在 [[index]] 段落上方！）
#  加速 `uv python install 3.x` 下载 Python 解释器
python-install-mirror = "https://registry.npmmirror.com/-/binary/python-build-standalone/"

# 2. PyPI 源配置（第三方包下载，可配置多个）
[[index]]
url = "https://mirrors.cloud.tencent.com/pypi/simple"
default = true

[[index]]
url = "https://pypi.tuna.tsinghua.edu.cn/simple"

[[index]]
url = "https://mirrors.aliyun.com/pypi/simple"

[[index]]
url = "https://repo.huaweicloud.com/repository/pypi/simple"

[[index]]
url = "https://pypi.doubanio.com/simple"

[[index]]
url = "https://pypi.mirrors.ustc.edu.cn/simple"

[[index]]
url = "https://pypi.org/simple"

[[index]]
url = "https://pypi.python.org/simple"

2. 单个项目配置

在项目中生成的配置文件pyproject.toml中添加

[tool.uv]
python-install-mirror = "https://registry.npmmirror.com/-/binary/python-build-standalone/"

八、常见问题答疑

1. 安装时 brew 提示找不到 uv？

本地 brew 索引过旧，先执行 brew update 更新索引，再安装即可；若更新缓慢，直接使用官方脚本安装。

2. 卸载时提示目录不存在？

正常现象，说明对应目录本无残留，跳过该命令即可，不影响整体清理效果。

3. uv 虚拟环境卸载后报错？

uv 创建的 .venv 仅适配 uv 环境，卸载后无法兼容原生 pip，直接删除项目 .venv，重新搭建原生虚拟环境即可。

4. 为什么不推荐 pip 安装 uv？

pip 安装的 uv 无法使用 uv self update 自更新，只能手动升级，且环境兼容性较差，容易出现路径冲突。

5.安装时无法下载tar.gz？

手动下载地址：https://github.com/astral-sh/uv/releases ，选择适合的版本下载，解压到指定目录，再配置环境变量。

6. 如何配置 uv python 下载目录

需要在环境变量中配置 UV_PYTHON_INSTALL_DIR 目录。

如：UV_PYTHON_INSTALL_DIR=/Users/whf/Apps/python_uv/python

以上就是Python中uv安装、卸载与实战的完整教程的详细内容，更多关于Python uv教程的资料请关注脚本之家其它相关文章！