---

前言

大家好～ 最近很多朋友问我，Python 开发中总被环境冲突、包安装缓慢、多版本切换麻烦等问题困扰，有没有一款工具能一站式解决这些痛点？答案必须是 UV ！ UV 是一款轻量、高速的 Python 包与环境管理工具，兼容 pip、virtualenv、pyenv 等传统工具，无需额外依赖，能快速实现 Python 版本管理、虚拟环境创建、包管理及项目初始化，实测比 pip 快 10 倍以上，大幅提升开发效率。不管你是刚入门的 Python 新手，还是经常处理多项目的资深开发者，掌握 UV 都能让你的开发流程更丝滑。

---

一、先搞懂：UV 到底能帮我们做什么？

在开始实操前，先明确 UV 的核心功能，避免盲目学习：

• ✅ 版本管理：无需 pyenv，一键下载、安装、切换多个 Python 版本（支持 CPython、PyPy）；
• ✅ 虚拟环境：快速创建、激活、退出虚拟环境，隔离不同项目依赖，避免版本冲突；
• ✅ 包管理：替代 pip，支持包的安装、升级、卸载、导出，下载速度更快、依赖解析更精准；
• ✅ 高效便捷：全局缓存依赖包，减少磁盘占用；无需提前安装 Python，可直接安装 UV；
• ✅ 多平台兼容：完美支持 macOS、Linux、Windows 三大系统，操作逻辑统一。

简单说，有了 UV，你再也不用同时记 pip、virtualenv、pyenv 等多个工具的命令，一个 UV 就能搞定所有环境和包相关的操作！

二、第一步：UV 安装（多系统适配，解决官方脚本报错）

UV 的安装非常简单，不同系统有对应的最优方案，经测试，官方默认安装脚本可能出现「invalid link」报错，优先推荐系统自带包管理器安装，报错时可切换备用方案。

2.1 macOS 系统安装

推荐使用 Homebrew 安装（最稳定，无报错），打开终端执行以下命令：

brew install uv

2.2 Linux 系统安装

有两种方案，优先尝试官方脚本，报错则切换备用方式：

# 方案1：官方脚本（若报错 invalid link，切换方案2）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 方案2：备用安装（适配部分 Linux 发行版）
wget -qO- https://astral.sh/uv/install.sh | sh

2.3 Windows 系统安装

Windows 11 及以上推荐使用 Winget 安装（自带工具，稳定无报错），低版本可切换官方脚本或备用方案：

# 方案1：Winget 安装（推荐）
winget install uv
# 方案2：官方脚本（若报错 invalid link，切换方案3）
irm https://astral.sh/uv/install.ps1 | iex
# 方案3：备用脚本（解决部分 Windows 环境报错）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

±

2.4 安装验证（必做步骤）

安装完成后，在终端执行以下命令，输出版本信息即表示安装成功：

uv --version

输出示例（版本号可能更新，无需完全一致）：

uv 0.8.14 (Homebrew 2025-08-28)

若提示「uv 不是内部或外部命令」，检查环境变量是否配置正确（macOS/Linux 可执行 source $HOME/\.local/bin/env 刷新环境变量）。

三、核心功能实操（最常用，必掌握）

UV 的核心功能分为 3 部分：Python 版本管理、虚拟环境管理、包管理，下面逐一拆解，每一步都附实操命令和说明。

3.1 Python 版本管理（无需 pyenv，一键搞定）

很多开发者需要同时处理多个 Python 版本的项目（比如有的项目用 3.9，有的用 3.12），UV 可以直接下载、切换版本，无需额外安装 pyenv。

3.1.1 查看所有可用 Python 版本

执行以下命令，可查看所有可下载、已安装的 Python 版本（包括 CPython、PyPy）：

uv python list

3.1.2 安装特定 Python 版本

根据项目需求，安装指定版本的 Python，常用场景命令如下：

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

# 安装指定具体版本（如 3.11.6，避免版本兼容问题）
uv python install 3.11.6

# 安装 PyPy 版本（轻量高效，适合生产环境）
uv python install pypy3.10

3.1.3 设置全局默认 Python 版本

设置后，所有终端都会使用该版本的 Python，无需每次切换：

uv python default 3.12

验证是否生效：

python --version # 输出 Python 3.12.x 即成功

3.1.4 固定项目 Python 版本（团队协作必备）

在项目根目录执行以下命令，会生成 \.python\-version 文件，标识项目所需 Python 版本，他人克隆项目后可快速适配：

uv python pin 3.11 # 固定为 3.11 版本

3.2 虚拟环境管理（隔离依赖，避免冲突）

虚拟环境是 Python 开发的必备技巧，可隔离不同项目的依赖包（比如 A 项目用 requests 2.20，B 项目用 requests 2.31），UV 创建和激活虚拟环境的操作比 virtualenv 更简洁。

3.2.1 创建虚拟环境（4种常用方式）

# 方式1：创建默认名称（.venv）的虚拟环境（推荐，符合行业规范）
uv venv

# 方式2：指定 Python 版本创建虚拟环境（如 3.11）
uv venv --python 3.11 .venv
uv venv --python=3.11 .venv # 两种写法均可

# 方式3：创建自定义名称的虚拟环境（区分不同项目）
uv venv --python 3.12 .venv312 # 适配 Python 3.12 项目

# 方式4：指定本地已安装的 Python 可执行文件路径（Windows 专用）
uv venv --python "C:\Python311\python.exe" .venv

3.2.2 激活虚拟环境（不同系统操作不同）

激活后，终端提示符前会出现 \(\.venv\) 或自定义名称标识，此时安装的包仅作用于当前虚拟环境：

# macOS/Linux 系统（终端执行）
source .venv/bin/activate

# Windows 系统（CMD/PowerShell 执行）
.venv\Scripts\activate
.venv37\Scripts\activate # 自定义名称环境激活

3.2.3 验证虚拟环境是否激活

python -VV # 查看当前环境的 Python 版本，确认与虚拟环境指定版本一致

3.2.4 退出虚拟环境（任意系统通用）

deactivate

3.3 包管理（替代 pip，更快更高效）

UV 的 uv pip 命令完全兼容 pip 的所有功能，且下载速度更快、依赖解析更精准，还支持全局缓存，重复安装包时无需重新下载。

3.3.1 安装包（常用场景）

# 安装最新版本的包（如 requests）
uv pip install requests

# 安装指定版本的包（避免版本兼容问题）
uv pip install requests==2.31.0

# 从 requirements.txt 文件批量安装依赖（迁移项目必备）
uv pip install -r requirements.txt

# 安装包到开发环境（仅开发时使用，如测试工具 pytest）
uv pip install --dev pytest

3.3.2 升级与卸载包

# 升级指定包到最新版本
uv pip upgrade requests

# 升级所有已安装的包（谨慎使用，避免版本冲突）
uv pip upgrade --all

# 卸载指定包（彻底删除，无残留）
uv pip uninstall requests

3.3.3 导出依赖（项目迁移、协作必备）

将当前环境的依赖包导出为 requirements.txt 文件，方便他人克隆项目后快速安装依赖：

# 导出当前环境所有依赖（包括开发依赖）
uv pip freeze > requirements.txt

# 导出生产环境依赖（排除开发依赖，上线必备）
uv pip freeze --production > requirements.txt

3.3.4 临时指定国内镜像源（解决下载缓慢）

若默认镜像源下载缓慢，可临时指定国内镜像源（如阿里云）：

uv pip install requests -i https://mirrors.aliyun.com/pypi/simple/

四、进阶技巧（提升效率，进阶必备）

4.1 清理 UV 缓存

UV 会缓存已安装的包，若缓存占用过多磁盘空间，可执行以下命令清理：

uv cache clean

4.2 卸载 UV

若需卸载 UV，先清理缓存和相关文件，再删除二进制文件：

# 1. 清理缓存和相关文件
uv cache clean
rm -r "$(uv python dir)"
rm -r "$(uv tool dir)"

# 2. 删除二进制文件（macOS/Linux）
rm ~/.local/bin/uv ~/.local/bin/uvx

# 2. 删除二进制文件（Windows）
rm $HOME.local\bin\uv.exe
rm $HOME.local\bin\uvx.exe

4.3 项目初始化（快速创建规范项目）

UV 可快速初始化一个 Python 项目，自动生成 pyproject\.toml 等规范文件：

uv init my_project # 创建名为 my_project 的项目
cd my_project # 进入项目目录

五、常见问题排查（新手必看，避坑指南）

问题1：安装 UV 后，执行 uv \-\-version 提示「命令不存在」

解决方案：检查环境变量是否配置正确。macOS/Linux 可执行source $HOME/\.local/bin/env 刷新环境变量，Windows 需重启终端或手动添加 UV 安装路径到环境变量。

问题2：使用官方脚本安装时，提示「invalid link」

解决方案：切换到对应系统的备用安装方案（如 macOS 用 Homebrew，Windows 用 Winget），避免使用官方脚本。

问题3：激活虚拟环境后，安装的包在退出后消失

原因：虚拟环境激活后，包仅安装在当前虚拟环境中，退出后会切换到全局环境，自然看不到。解决方案：重新激活对应的虚拟环境即可。

问题4：安装 Python 版本时，下载速度缓慢

解决方案：临时指定国内镜像源，或检查网络连接，若多次失败，可尝试更换网络后重新执行安装命令。

六、总结

UV 作为一款一站式 Python 环境与包管理工具，凭借其高速、简洁、兼容的特点，完美解决了传统工具的痛点。通过这篇教程，你已经掌握了 UV 的核心用法：从多系统安装，到 Python 版本管理、虚拟环境创建、包管理，再到进阶技巧和问题排查，足够覆盖日常开发的所有场景。

建议新手从「虚拟环境创建 + 包安装/导出」开始练习，熟悉后再尝试版本管理和进阶技巧，用 UV 简化你的 Python 开发流程，告别环境冲突和繁琐操作～

如果在使用过程中遇到其他问题，欢迎在评论区留言，一起交流学习！

✨ 最后，附上 UV 官方文档链接，如需更详细的功能说明，可前往查看：https://docs.astral.sh/uv/