1322 lines
28 KiB
Markdown
1322 lines
28 KiB
Markdown
# 极速 Python 包管理神器：uv 体验报告
|
||
|
||
> 如果你还在用 pip 安装包、用 conda 创建环境、用 virtualenv 管理虚拟环境，那你一定要试试 uv。这篇文章，我会详细介绍这款让我"相见恨晚"的 Python 包管理工具。
|
||
|
||
## 前言
|
||
|
||
作为一名 Python 开发者，我每天都要和包管理打交道。从最初的 easy_install，到后来的 pip，再到 conda、virtualenv、poetry、pyenv... 市面上的工具我几乎都用过。
|
||
|
||
直到有一天，我遇到了 **uv**。
|
||
|
||
说实话，第一次看到 uv 的介绍时，我是持怀疑态度的："又一个 Python 包管理工具？能比 pip 好用多少？"
|
||
|
||
但当我真正用它跑了几条命令之后，我的心态发生了巨大转变：**这玩意儿是真的香。**
|
||
|
||
所以写了这篇博客，把 uv 推荐给更多 Python 开发者。如果你也在为 Python 环境管理烦恼，这篇文章或许能帮到你。
|
||
|
||
---
|
||
|
||
## 第一章：初识 uv —— 它到底是什么？
|
||
|
||
### 1.1 来自 Astral 的明星产品
|
||
|
||
uv 是由 **Astral** 公司开发的工具。Astral 这个名字你可能不熟悉，但他们的产品你一定听说过：
|
||
|
||
- **ruff** —— Python 代码检查工具，速度比 flake8 快 10-100 倍
|
||
- **ruff formatter** —— Python 代码格式化工具
|
||
|
||
没错，uv 和 ruff 是同一个公司的产品。这个公司专注于打造"极速"工具，而 uv 正是他们针对 Python 生态的包管理解决方案。
|
||
|
||
### 1.2 用 Rust 编写，为速度而生
|
||
|
||
uv 最大的特点是：**快**。
|
||
|
||
它是用 Rust 编写的，这让它在性能上远超用 Python 写的 pip、conda 等工具。具体有多快？官方给出的数据是：
|
||
|
||
| 操作 | pip | uv |
|
||
|------|-----|-----|
|
||
| 安装 requests | ~2.5 秒 | ~0.2 秒 |
|
||
| 创建虚拟环境 | ~8 秒 | ~0.2 秒 |
|
||
| 解析依赖 | 数十秒 | 毫秒级 |
|
||
|
||
这些数据可能因系统环境而异，但总体来说，uv 的速度是 pip 的 **10-100 倍**。
|
||
|
||
### 1.3 一个工具，替代六个
|
||
|
||
uv 的设计理念是"大一统"——用一个工具解决所有 Python 环境管理问题：
|
||
|
||
| 工具 | uv 替代 |
|
||
|------|---------|
|
||
| pip | ✅ `uv pip install` |
|
||
| pip-tools | ✅ `uv pip compile` |
|
||
| pipx | ✅ `uv tool install` |
|
||
| poetry | ✅ `uv init`, `uv add` |
|
||
| pyenv | ✅ `uv python install` |
|
||
| venv / virtualenv | ✅ `uv venv` |
|
||
|
||
没错，你不需要安装 pip、conda、poetry、pyenv、virtualenv、pipx 六个工具，只需要一个 uv。
|
||
|
||
### 1.4 为什么要换掉 pip？
|
||
|
||
你可能会问："pip 我用了这么多年好好的，为什么要换？"
|
||
|
||
坦白说，如果你的项目规模不大、依赖不多，pip 完全够用。但随着项目复杂度增加，你会遇到这些问题：
|
||
|
||
**pip 太慢**：安装一个 numpy 可能要等半分钟，遇到依赖复杂的大包（如 tensorflow、torch）更是要等几分钟。
|
||
|
||
**环境切换麻烦**：要在多个 Python 版本和虚拟环境之间切换，你需要 pyenv、virtualenv、conda 等工具来回切换。
|
||
|
||
**依赖管理不完善**：pip freeze 生成的 requirements.txt 可能包含不必要的依赖，pip install -r requirements.txt 有时还会遇到版本冲突。
|
||
|
||
uv 正是为了解决这些问题而设计的。它不仅快，而且提供了统一的依赖管理方案。
|
||
|
||
---
|
||
|
||
## 第二章：安装 uv —— 5 分钟搞定
|
||
|
||
### 2.1 Windows 安装（推荐 PowerShell）
|
||
|
||
在 Windows 上安装 uv 有多种方式，我推荐使用 PowerShell 安装脚本，这是最简单的方式：
|
||
|
||
```powershell
|
||
# 使用 PowerShell 安装脚本（推荐）
|
||
irm https://astral.sh/uv/install.ps1 | iex
|
||
```
|
||
|
||
或者，如果你已经安装了 scoop，可以用这个方式：
|
||
|
||
```powershell
|
||
# 使用 scoop 安装
|
||
scoop install uv
|
||
```
|
||
|
||
另外，Windows 用户也可以用 winget：
|
||
|
||
```powershell
|
||
# 使用 winget 安装
|
||
winget install --id=astral-sh.uv -e
|
||
```
|
||
|
||
### 2.2 macOS 安装
|
||
|
||
macOS 用户可以用 Homebrew：
|
||
|
||
```bash
|
||
# 使用 Homebrew 安装
|
||
brew install uv
|
||
```
|
||
|
||
### 2.3 Linux 安装
|
||
|
||
Linux 用户可以用 curl：
|
||
|
||
```bash
|
||
# 使用 curl 安装（适用于大多数 Linux 发行版）
|
||
curl -LsSf https://astral.sh/uv/install.sh | sh
|
||
```
|
||
|
||
或者通过包管理器：
|
||
|
||
```bash
|
||
# Debian/Ubuntu
|
||
apt install uv
|
||
|
||
# Fedora
|
||
dnf install uv
|
||
```
|
||
|
||
### 2.4 验证安装
|
||
|
||
安装完成后，打开一个新的终端窗口（记得重新打开，因为 PATH 可能需要刷新），输入：
|
||
|
||
```powershell
|
||
uv --version
|
||
# 输出应该类似：
|
||
# uv 0.5.x
|
||
```
|
||
|
||
如果显示了版本号，说明安装成功。
|
||
|
||
### 2.5 遇到问题？
|
||
|
||
**问题 1：无法运行脚本**
|
||
|
||
如果遇到"禁止运行脚本"的错误，需要调整 PowerShell 的执行策略：
|
||
|
||
```powershell
|
||
# 查看当前执行策略
|
||
Get-ExecutionPolicy
|
||
|
||
# 如果是 Restricted，修改为 RemoteSigned
|
||
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
|
||
|
||
# 然后重新运行安装命令
|
||
irm https://astral.sh/uv/install.ps1 | iex
|
||
```
|
||
|
||
**问题 2：找不到 uv 命令**
|
||
|
||
安装后需要刷新环境变量，或者手动将 uv 的路径添加到 PATH：
|
||
|
||
```powershell
|
||
# 查看 uv 的安装路径
|
||
where.exe uv
|
||
|
||
# 如果找到了，手动添加到 PATH
|
||
$env:PATH += ";C:\Users\你的用户名\.local\bin"
|
||
```
|
||
|
||
---
|
||
|
||
## 第三章：虚拟环境管理 —— 轻量快速
|
||
|
||
### 3.1 创建虚拟环境
|
||
|
||
这是 uv 最基础的功能之一。创建虚拟环境只需要一条命令：
|
||
|
||
```powershell
|
||
# 创建默认环境（.venv）
|
||
uv venv
|
||
|
||
# 创建自定义名称的环境
|
||
uv venv myenv
|
||
|
||
# 指定 Python 版本
|
||
uv venv --python 3.11 myenv
|
||
uv venv --python 3.12 myenv
|
||
```
|
||
|
||
查看可用的 Python 版本：
|
||
|
||
```powershell
|
||
# 列出所有可用版本（包括已安装和可下载）
|
||
uv python list
|
||
|
||
# 只显示已安装的版本
|
||
uv python list --only-installed
|
||
```
|
||
|
||
### 3.2 激活虚拟环境
|
||
|
||
创建环境后，需要激活才能使用：
|
||
|
||
```powershell
|
||
# PowerShell
|
||
.venv\Scripts\Activate.ps1
|
||
|
||
# CMD
|
||
.venv\Scripts\activate.bat
|
||
|
||
# Bash (Git Bash / WSL / macOS / Linux)
|
||
source .venv/Scripts/activate
|
||
```
|
||
|
||
激活成功后，终端提示符会变化，显示当前环境的名称。
|
||
|
||
### 3.3 退出虚拟环境
|
||
|
||
```bash
|
||
# 通用方法
|
||
deactivate
|
||
|
||
# 或者直接关闭当前终端
|
||
```
|
||
|
||
### 3.4 删除虚拟环境
|
||
|
||
删除虚拟环境非常简单：
|
||
|
||
```powershell
|
||
# Windows PowerShell
|
||
Remove-Item -Recurse -Force .venv
|
||
|
||
# 或者用 rd 命令
|
||
rd /s /q .venv
|
||
|
||
# Linux/macOS/Bash
|
||
rm -rf .venv
|
||
```
|
||
|
||
uv 创建的虚拟环境就是普通的 `.venv` 目录，不需要专门的删除命令。
|
||
|
||
### 3.5 与 conda 对比
|
||
|
||
我之前一直用 conda 管理环境，但 conda 有几个让人头疼的问题：
|
||
|
||
**问题 1：体积太大**
|
||
|
||
conda 本身加上 base 环境，少说也要 1-2GB。而 uv 创建的虚拟环境，只有 Python 解释器本身，几个 MB 而已。
|
||
|
||
**问题 2：创建慢**
|
||
|
||
conda create 创建环境可能要等几十秒，而 uv venv 只要不到 1 秒。
|
||
|
||
**问题 3：频道混乱**
|
||
|
||
conda 有 main、conda-forge、pytorch 等多个频道，有时候安装包会遇到找不到、版本冲突的问题。uv 直接用 PyPI，干净利落。
|
||
|
||
**对比表**
|
||
|
||
| 特性 | uv | conda |
|
||
|------|-----|-------|
|
||
| 创建速度 | <1 秒 | 10-30 秒 |
|
||
| 初始体积 | ~5 MB | ~500 MB |
|
||
| 包来源 | PyPI | 多频道 |
|
||
| 环境切换 | 快 | 慢 |
|
||
| 命令复杂度 | 简单 | 复杂 |
|
||
|
||
### 3.6 实际体验
|
||
|
||
让我用一个实际的例子展示 uv 的速度：
|
||
|
||
```powershell
|
||
# 用 uv 创建环境
|
||
Measure-Command { uv venv --python 3.11 }
|
||
# 结果：大约 0.2 秒
|
||
|
||
# 对比：用 conda 创建环境
|
||
# Measure-Command { conda create -n test -y python=3.11 }
|
||
# 结果：大约 30 秒
|
||
```
|
||
|
||
这个差距是巨大的，尤其是在你需要频繁创建/删除环境的时候。
|
||
|
||
---
|
||
|
||
## 第四章：包管理 —— pip 的完美替代
|
||
|
||
### 4.1 安装包
|
||
|
||
这是 uv 最常用的功能。`uv pip install` 可以完全替代 `pip install`：
|
||
|
||
```powershell
|
||
# 安装单个包
|
||
uv pip install requests
|
||
|
||
# 安装多个包
|
||
uv pip install requests numpy pandas
|
||
|
||
# 指定版本
|
||
uv pip install requests==2.28.0
|
||
uv pip install "requests>=2.28,<3.0"
|
||
|
||
# 从 requirements.txt 安装
|
||
uv pip install -r requirements.txt
|
||
|
||
# 从 Git 安装
|
||
uv pip install git+https://github.com/user/repo.git
|
||
|
||
# 从本地路径安装
|
||
uv pip install ./mypackage
|
||
|
||
# 安装可编辑模式（开发模式）
|
||
uv pip install -e ./mypackage
|
||
```
|
||
|
||
### 4.2 卸载包
|
||
|
||
```powershell
|
||
# 卸载单个包
|
||
uv pip uninstall requests
|
||
|
||
# 卸载多个包
|
||
uv pip uninstall requests numpy
|
||
|
||
# 从 requirements.txt 卸载
|
||
uv pip uninstall -r requirements.txt
|
||
```
|
||
|
||
### 4.3 查看已安装的包
|
||
|
||
```powershell
|
||
# 以 requirements 格式输出
|
||
uv pip freeze
|
||
|
||
# 以列表格式输出（更易读）
|
||
uv pip list
|
||
```
|
||
|
||
### 4.4 同步依赖
|
||
|
||
这是 uv 的一个特色功能。当你有 `requirements.txt` 或 `pyproject.toml` 时，可以用 `sync` 命令确保环境与文件一致：
|
||
|
||
```powershell
|
||
# 同步到 requirements.txt
|
||
uv pip sync requirements.txt
|
||
|
||
# 同步到 pyproject.toml
|
||
uv sync
|
||
|
||
# 安装开发依赖
|
||
uv sync --group dev
|
||
```
|
||
|
||
### 4.5 性能对比实测
|
||
|
||
让我实际测试一下 uv 和 pip 的速度差距：
|
||
|
||
```powershell
|
||
# 测试 1：安装 requests
|
||
# pip
|
||
Measure-Command { pip install requests }
|
||
# 耗时：约 3-5 秒
|
||
|
||
# uv
|
||
Measure-Command { uv pip install requests }
|
||
# 耗时：约 0.3-0.5 秒
|
||
|
||
# 测试 2：安装 numpy（更大的包）
|
||
# pip
|
||
Measure-Command { pip install numpy }
|
||
# 耗时：约 10-15 秒
|
||
|
||
# uv
|
||
Measure-Command { uv pip install numpy }
|
||
# 耗时：约 1-2 秒
|
||
|
||
# 测试 3：安装 pandas（依赖复杂）
|
||
# pip
|
||
Measure-Command { pip install pandas }
|
||
# 耗时：约 30-60 秒
|
||
|
||
# uv
|
||
Measure-Command { uv pip install pandas }
|
||
# 耗时：约 3-5 秒
|
||
```
|
||
|
||
可以看到，包越大、依赖越复杂，uv 的优势越明显。
|
||
|
||
### 4.6 依赖解析
|
||
|
||
uv 内置了强大的依赖解析器，能够：
|
||
|
||
- **并行下载**：同时下载多个包
|
||
- **智能缓存**：避免重复下载
|
||
- **冲突检测**：安装前检测版本冲突
|
||
|
||
```powershell
|
||
# 查看包的信息
|
||
uv pip show requests
|
||
|
||
# 检查是否有更新
|
||
uv pip list --outdated
|
||
|
||
# 升级包到最新版本
|
||
uv pip install --upgrade requests
|
||
```
|
||
|
||
### 4.7 离线安装
|
||
|
||
uv 支持离线模式，这在某些场景下很有用：
|
||
|
||
```powershell
|
||
# 先在有网环境下载包到目录
|
||
uv pip install requests --target ./packages
|
||
|
||
# 在无网环境从目录安装
|
||
uv pip install --offline --target ./packages requests
|
||
```
|
||
|
||
---
|
||
|
||
## 第五章：Python 版本管理 —— 一个命令切换
|
||
|
||
### 5.1 列出可用版本
|
||
|
||
```powershell
|
||
# 列出所有可用版本
|
||
uv python list
|
||
|
||
# 输出示例：
|
||
# cpython-3.13.0+cp313-cp313-manylinux_2_17-x86_64.manylinux2014_x86_64
|
||
# cpython-3.12.5+cp312-cp312-manylinux_2_17-x86_64.manylinux2014_x86_64
|
||
# cpython-3.11.9+cp311-cp311-manylinux_2_17-x86_64.manylinux2014_x86_64
|
||
# ...
|
||
```
|
||
|
||
### 5.2 安装指定版本
|
||
|
||
```powershell
|
||
# 安装 Python 3.12
|
||
uv python install 3.12
|
||
|
||
# 安装特定小版本
|
||
uv python install 3.11.9
|
||
|
||
# 安装最新 3.11
|
||
uv python install 3.11
|
||
|
||
# 安装所有受支持的版本
|
||
uv python install 3.8 3.9 3.10 3.11 3.12 3.13
|
||
```
|
||
|
||
### 5.3 卸载版本
|
||
|
||
```powershell
|
||
# 卸载指定版本
|
||
uv python uninstall 3.10
|
||
|
||
# 卸载多个版本
|
||
uv python uninstall 3.8 3.9
|
||
```
|
||
|
||
### 5.4 在项目中指定版本
|
||
|
||
在 `pyproject.toml` 中指定项目的 Python 版本要求：
|
||
|
||
```toml
|
||
[project]
|
||
name = "myproject"
|
||
version = "0.1.0"
|
||
requires-python = ">=3.11"
|
||
```
|
||
|
||
或者创建 `.python-version` 文件：
|
||
|
||
```
|
||
3.11
|
||
```
|
||
|
||
这样 `uv sync` 时会自动安装正确的 Python 版本。
|
||
|
||
### 5.5 实际使用场景
|
||
|
||
**场景 1：维护多个项目**
|
||
|
||
假设你有两个项目，一个需要 Python 3.11，另一个需要 Python 3.12：
|
||
|
||
```powershell
|
||
# 项目 A（Python 3.11）
|
||
cd project-a
|
||
uv venv --python 3.11
|
||
uv pip install -r requirements.txt
|
||
|
||
# 项目 B（Python 3.12）
|
||
cd ../project-b
|
||
uv venv --python 3.12
|
||
uv pip install -r requirements.txt
|
||
```
|
||
|
||
两个项目使用不同的 Python 版本，互不影响。
|
||
|
||
**场景 2：测试多版本兼容性**
|
||
|
||
```powershell
|
||
# 安装多个版本
|
||
uv python install 3.8 3.9 3.10 3.11 3.12
|
||
|
||
# 在每个版本下运行测试
|
||
for v in 3.8 3.9 3.10 3.11 3.12; do
|
||
uv venv --python $v test-env
|
||
.venv\Scripts\Activate.ps1
|
||
uv run pytest
|
||
deactivate
|
||
Remove-Item -Recurse -Force test-env
|
||
done
|
||
```
|
||
|
||
---
|
||
|
||
## 第六章：项目管理 —— 从初始化到运行
|
||
|
||
### 6.1 创建新项目
|
||
|
||
`uv init` 可以快速初始化新项目：
|
||
|
||
```powershell
|
||
# 创建基础项目
|
||
uv init myproject
|
||
|
||
# 创建可打包项目（更完整的项目结构）
|
||
uv init --package myproject
|
||
|
||
# 创建库项目
|
||
uv init --lib mylibrary
|
||
|
||
# 创建脚本项目（单文件脚本）
|
||
uv init --script myscript.py
|
||
```
|
||
|
||
### 6.2 项目结构
|
||
|
||
`uv init` 会创建标准的 Python 项目结构：
|
||
|
||
```
|
||
myproject/
|
||
├── .python-version # Python 版本要求
|
||
├── pyproject.toml # 项目配置
|
||
├── README.md # 自述文件
|
||
├── src/
|
||
│ └── myproject/ # 源代码目录
|
||
│ ├── __init__.py
|
||
│ └── main.py
|
||
└── tests/
|
||
└── test_example.py # 测试文件
|
||
```
|
||
|
||
`pyproject.toml` 的内容：
|
||
|
||
```toml
|
||
[project]
|
||
name = "myproject"
|
||
version = "0.1.0"
|
||
description = "Add your description here"
|
||
readme = "README.md"
|
||
requires-python = ">=3.12"
|
||
dependencies = []
|
||
```
|
||
|
||
### 6.3 添加依赖
|
||
|
||
进入项目目录，添加依赖：
|
||
|
||
```powershell
|
||
cd myproject
|
||
|
||
# 添加生产依赖
|
||
uv add requests
|
||
uv add "flask>=2.0"
|
||
uv add "numpy>=1.24"
|
||
|
||
# 添加开发依赖
|
||
uv add --dev pytest
|
||
uv add --dev black
|
||
uv add --dev ruff
|
||
|
||
# 添加可选依赖
|
||
uv add --optional gui pyqt6
|
||
```
|
||
|
||
添加后，`pyproject.toml` 会自动更新：
|
||
|
||
```toml
|
||
[project]
|
||
name = "myproject"
|
||
version = "0.1.0"
|
||
requires-python = ">=3.12"
|
||
dependencies = [
|
||
"requests>=2.28.0",
|
||
"flask>=2.0",
|
||
]
|
||
|
||
[project.optional-dependencies]
|
||
gui = ["pyqt6"]
|
||
|
||
[tool.uv]
|
||
dev-dependencies = [
|
||
"pytest>=7.0",
|
||
"black>=23.0",
|
||
]
|
||
```
|
||
|
||
### 6.4 运行项目
|
||
|
||
```powershell
|
||
# 运行主程序
|
||
uv run python src/myproject/main.py
|
||
|
||
# 运行测试
|
||
uv run pytest
|
||
|
||
# 运行脚本
|
||
uv run python myscript.py
|
||
|
||
# 运行带参数的脚本
|
||
uv run python myscript.py --arg1 value1
|
||
```
|
||
|
||
### 6.5 锁定依赖
|
||
|
||
在团队协作中，锁定依赖版本很重要：
|
||
|
||
```powershell
|
||
# 生成锁文件
|
||
uv lock
|
||
|
||
# 同步到锁文件
|
||
uv sync
|
||
|
||
# 升级依赖到最新兼容版本
|
||
uv lock --upgrade
|
||
|
||
# 升级特定包
|
||
uv lock --upgrade requests
|
||
```
|
||
|
||
`uv lock` 会生成 `uv.lock` 文件，这是项目的依赖锁文件，应该提交到版本控制系统。
|
||
|
||
### 6.6 完整的项目工作流
|
||
|
||
```powershell
|
||
# 1. 创建项目
|
||
uv init myproject
|
||
cd myproject
|
||
|
||
# 2. 添加依赖
|
||
uv add flask requests
|
||
|
||
# 3. 添加开发依赖
|
||
uv add --dev pytest black ruff
|
||
|
||
# 4. 锁定依赖
|
||
uv lock
|
||
|
||
# 5. 在其他机器上同步
|
||
uv sync
|
||
```
|
||
|
||
这个工作流非常简洁，比使用多个工具（pip、pip-tools、poetry）组合要简单很多。
|
||
|
||
---
|
||
|
||
## 第七章：工具管理（uvx）—— 告别全局安装
|
||
|
||
### 7.1 什么是 uvx？
|
||
|
||
`uvx` 是 uv 的一个配套工具，类似于 Node.js 的 `npx`。它可以**临时运行**工具，而不需要全局安装。
|
||
|
||
### 7.2 运行常用工具
|
||
|
||
```powershell
|
||
# 运行 black 代码格式化
|
||
uvx black .
|
||
|
||
# 运行 ruff 代码检查
|
||
uvx ruff check .
|
||
|
||
# 运行 ruff 格式化
|
||
uvx ruff format .
|
||
|
||
# 启动 Jupyter Lab
|
||
uvx jupyter lab
|
||
|
||
# 运行 httpie（HTTP 客户端）
|
||
uvx --from httpie http GET example.com
|
||
|
||
# 运行 mypy 类型检查
|
||
uvx mypy src/
|
||
|
||
# 运行 isort 导入排序
|
||
uvx isort src/
|
||
```
|
||
|
||
### 7.3 安装全局工具
|
||
|
||
如果你经常使用某个工具，可以全局安装它：
|
||
|
||
```powershell
|
||
# 安装 black 为全局工具
|
||
uv tool install black
|
||
|
||
# 安装多个工具
|
||
uv tool install ruff
|
||
uv tool install pytest
|
||
uv tool install httpie
|
||
|
||
# 从 Git 安装
|
||
uv tool install --git https://github.com/psf/black black
|
||
|
||
# 从本地路径安装
|
||
uv tool install --path ./mytool mytool
|
||
```
|
||
|
||
### 7.4 管理已安装的工具
|
||
|
||
```powershell
|
||
# 列出已安装的工具
|
||
uv tool list
|
||
|
||
# 输出示例：
|
||
# black v24.1.0
|
||
# ruff v0.1.0
|
||
# pytest v8.0.0
|
||
|
||
# 升级工具
|
||
uv tool upgrade black
|
||
|
||
# 升级所有工具
|
||
uv tool upgrade --all
|
||
|
||
# 卸载工具
|
||
uv tool uninstall black
|
||
```
|
||
|
||
### 7.5 工具来源
|
||
|
||
uv 支持多种工具来源：
|
||
|
||
```powershell
|
||
# 从 PyPI 安装（默认）
|
||
uv tool install black
|
||
|
||
# 从 Git 仓库安装
|
||
uv tool install --git https://github.com/psf/black.git black
|
||
|
||
# 从 URL 安装
|
||
uv tool install --from-url https://example.com/tool.whl mytool
|
||
|
||
# 从本地文件安装
|
||
uv tool install --path ./tool.whl mytool
|
||
|
||
# 从特定版本安装
|
||
uv tool install --python 3.11 black
|
||
```
|
||
|
||
### 7.6 使用场景
|
||
|
||
**场景 1：一次性工具**
|
||
|
||
有些工具你可能只偶尔用一次，全局安装太浪费，uvx 就很合适：
|
||
|
||
```powershell
|
||
# 用 httpie 调试 API
|
||
uvx --from httpie http POST api.example.com/items name=test
|
||
|
||
# 用 cowsay 玩一下
|
||
uvx --from cowsay cow "Hello from uvx"
|
||
```
|
||
|
||
**场景 2：尝试新工具**
|
||
|
||
想试试某个新工具，但不确定会不会长期使用：
|
||
|
||
```powershell
|
||
# 先用 uvx 试试
|
||
uvx --from ruff-lsp ruff-lsp
|
||
|
||
# 觉得好用再全局安装
|
||
uv tool install ruff-lsp
|
||
```
|
||
|
||
**场景 3：不同项目用不同版本**
|
||
|
||
有时候不同的项目需要不同版本的工具：
|
||
|
||
```powershell
|
||
# 项目 A 用新版本
|
||
uvx ruff@latest check .
|
||
|
||
# 项目 B 用稳定版本
|
||
uvx ruff@0.3.0 check .
|
||
```
|
||
|
||
---
|
||
|
||
## 第八章：实战案例 —— 我的日常开发工作流
|
||
|
||
### 8.1 场景一：快速创建数据分析环境
|
||
|
||
这是我的日常场景之一。假设我需要分析一批数据：
|
||
|
||
```powershell
|
||
# 创建环境
|
||
uv venv --python 3.11 data-analysis
|
||
|
||
# 激活环境
|
||
.venv\Scripts\Activate.ps1
|
||
|
||
# 安装数据处理相关的包
|
||
uv pip install pandas numpy matplotlib seaborn jupyter
|
||
|
||
# 启动 Jupyter Lab
|
||
uv run jupyter lab
|
||
```
|
||
|
||
从创建环境到启动 Jupyter，整个过程不到 30 秒。
|
||
|
||
### 8.2 场景二：深度学习项目环境
|
||
|
||
深度学习项目通常需要较大的依赖包，安装时间长：
|
||
|
||
```powershell
|
||
# 创建环境
|
||
uv venv --python 3.10 dl-project
|
||
|
||
# 激活环境
|
||
.venv\Scripts\Activate.ps1
|
||
|
||
# 安装 PyTorch（GPU 版本）
|
||
uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
|
||
|
||
# 安装其他常用包
|
||
uv pip install transformers datasets accelerate
|
||
|
||
# 安装开发依赖
|
||
uv pip install pytest pytest-cov black ruff
|
||
|
||
# 锁定依赖
|
||
uv lock
|
||
|
||
# 分享给队友时，队友只需要：
|
||
uv sync
|
||
```
|
||
|
||
### 8.3 场景三：Web API 开发
|
||
|
||
用 FastAPI 开发 REST API：
|
||
|
||
```powershell
|
||
# 创建项目
|
||
uv init fastapi-demo --package
|
||
cd fastapi-demo
|
||
|
||
# 添加依赖
|
||
uv add fastapi uvicorn pydantic sqlalchemy
|
||
|
||
# 添加开发依赖
|
||
uv add --dev pytest httpx
|
||
|
||
# 创建应用代码（src/fastapi_demo/main.py）
|
||
# ...
|
||
|
||
# 运行开发服务器
|
||
uv run uvicorn src.fastapi_demo:app --reload
|
||
```
|
||
|
||
### 8.4 场景四：多项目维护
|
||
|
||
假设你有三个项目需要同时维护：
|
||
|
||
```powershell
|
||
# 项目 1：Web 服务（Flask + Gunicorn）
|
||
cd web-service
|
||
uv run python -c "import flask; print(flask.__version__)"
|
||
|
||
# 项目 2：数据分析脚本
|
||
cd ../data-analysis
|
||
uv run python scripts/analysis.py
|
||
|
||
# 项目 3：CLI 工具
|
||
cd ../cli-tool
|
||
uv run mytool --help
|
||
```
|
||
|
||
每个项目有独立的虚拟环境和依赖，互不干扰。
|
||
|
||
### 8.5 对比我之前的 .NET 开发经验
|
||
|
||
我之前做过 .NET 开发，dotnet CLI 的工作流让我印象深刻：
|
||
|
||
```bash
|
||
# dotnet CLI 工作流
|
||
dotnet new webapi -n MyApi
|
||
cd MyApi
|
||
dotnet add package Microsoft.EntityFrameworkCore
|
||
dotnet run
|
||
|
||
# uv 工作流（几乎一样！）
|
||
uv init myapi --package
|
||
cd myapi
|
||
uv add fastapi uvicorn
|
||
uv run uvicorn src.myapi:app --reload
|
||
```
|
||
|
||
uv 的设计理念和 dotnet CLI 很相似：用统一的命令处理项目全生命周期。这种一致性让从 .NET 转向 Python 的开发者很容易上手。
|
||
|
||
### 8.6 完整的团队协作流程
|
||
|
||
假设你要和新队友协作开发项目：
|
||
|
||
```powershell
|
||
# 1. 你初始化项目并锁定依赖
|
||
uv init team-project
|
||
cd team-project
|
||
uv add requests flask
|
||
uv lock
|
||
|
||
# 2. 提交到 Git
|
||
git add .
|
||
git commit -m "Initial project with dependencies"
|
||
|
||
# 3. 队友克隆项目
|
||
git clone https://github.com/team/team-project.git
|
||
cd team-project
|
||
|
||
# 4. 队友同步环境
|
||
uv sync
|
||
|
||
# 5. 队友开始开发
|
||
uv run python src/main.py
|
||
```
|
||
|
||
队友只需要一条 `uv sync` 命令，就能创建和你完全一致的开发环境。
|
||
|
||
---
|
||
|
||
## 第九章：进阶技巧与最佳实践
|
||
|
||
### 9.1 依赖组管理
|
||
|
||
uv 支持将依赖分组管理，这在大型项目中很有用：
|
||
|
||
```powershell
|
||
# 添加开发依赖组
|
||
uv add --group dev pytest pytest-cov black ruff mypy
|
||
|
||
# 添加测试依赖组
|
||
uv add --group test httpx coverage
|
||
|
||
# 添加文档依赖组
|
||
uv add --group docs sphinx sphinx-rtd-theme
|
||
|
||
# 只同步特定组
|
||
uv sync --group dev # 只安装开发依赖
|
||
uv sync --group test # 只安装测试依赖
|
||
uv sync # 安装所有依赖（包括所有组）
|
||
|
||
# 从特定组卸载
|
||
uv remove --group dev black
|
||
```
|
||
|
||
在 `pyproject.toml` 中：
|
||
|
||
```toml
|
||
[tool.uv]
|
||
dev-dependencies = [
|
||
"pytest>=7.0",
|
||
"black>=23.0",
|
||
"ruff>=0.1.0",
|
||
"mypy>=1.0",
|
||
]
|
||
|
||
[tool.uv.group.test]
|
||
dependencies = [
|
||
"httpx>=0.24",
|
||
"coverage>=7.0",
|
||
]
|
||
```
|
||
|
||
### 9.2 依赖解析与锁定
|
||
|
||
uv 的依赖解析非常强大：
|
||
|
||
```powershell
|
||
# 生成锁文件
|
||
uv lock
|
||
|
||
# 查看依赖树
|
||
uv tree
|
||
|
||
# 升级所有依赖到最新兼容版本
|
||
uv lock --upgrade
|
||
|
||
# 升级特定包
|
||
uv lock --upgrade numpy
|
||
|
||
# 查看可升级的包
|
||
uv pip list --outdated
|
||
```
|
||
|
||
### 9.3 缓存管理
|
||
|
||
uv 会缓存下载的包以加快后续安装：
|
||
|
||
```powershell
|
||
# 查看缓存目录
|
||
uv cache dir
|
||
# 输出：C:\Users\用户名\AppData\Local\uv\Cache
|
||
|
||
# 清理所有缓存
|
||
uv cache clean
|
||
|
||
# 清理未使用的缓存
|
||
uv cache prune
|
||
|
||
# 设置自定义缓存目录
|
||
$env:UV_CACHE_DIR = "D:\uv-cache"
|
||
```
|
||
|
||
### 9.4 离线环境
|
||
|
||
**场景 1：从目标目录安装**
|
||
|
||
```powershell
|
||
# 在有网环境下载包到目录
|
||
uv pip install requests numpy --target ./packages
|
||
|
||
# 在无网环境安装
|
||
uv pip install --offline --target ./packages requests numpy
|
||
```
|
||
|
||
**场景 2：从 wheel 文件安装**
|
||
|
||
```powershell
|
||
# 在有网环境构建 wheel
|
||
uv pip wheel requests numpy
|
||
|
||
# wheel 文件会保存到当前目录
|
||
ls *.whl
|
||
|
||
# 在无网环境安装
|
||
uv pip install requests-*.whl numpy-*.whl
|
||
```
|
||
|
||
### 9.5 环境变量配置
|
||
|
||
uv 支持多种环境变量：
|
||
|
||
```bash
|
||
# 指定默认 Python 版本
|
||
UV_PYTHON=3.11
|
||
|
||
# 指定缓存目录
|
||
UV_CACHE_DIR=/path/to/cache
|
||
|
||
# 禁用进度条（CI 环境有用）
|
||
UV_NO_PROGRESS=1
|
||
|
||
# 并行下载数量
|
||
UV_CONCURRENT_DOWNLOADS=50
|
||
|
||
# 超时时间（秒）
|
||
UV_HTTP_TIMEOUT=300
|
||
|
||
# 代理设置
|
||
UV_HTTP_PROXY=http://proxy:8080
|
||
UV_HTTPS_PROXY=http://proxy:8080
|
||
```
|
||
|
||
### 9.6 使用配置文件
|
||
|
||
你可以在项目根目录创建 `uv.toml` 进行配置：
|
||
|
||
```toml
|
||
# uv.toml
|
||
python-version = "3.11"
|
||
|
||
# 索引 URL（使用国内镜像加速）
|
||
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
|
||
|
||
# 严格模式（不兼容的依赖会报错）
|
||
resolution = "strict"
|
||
|
||
# 预发布版本
|
||
prerelease = "allow"
|
||
```
|
||
|
||
使用清华镜像加速（国内用户）：
|
||
|
||
```toml
|
||
index-url = "https://pypi.tuna.tsinghua.edu.cn/simple"
|
||
```
|
||
|
||
### 9.7 与 Docker 配合使用
|
||
|
||
在 Dockerfile 中使用 uv：
|
||
|
||
```dockerfile
|
||
# 使用官方 Python 镜像
|
||
FROM python:3.12-slim
|
||
|
||
# 安装 uv
|
||
COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv
|
||
|
||
WORKDIR /app
|
||
|
||
# 复制依赖文件
|
||
COPY pyproject.toml uv.lock ./
|
||
|
||
# 创建虚拟环境并安装依赖（层缓存优化）
|
||
RUN uv sync --frozen --no-install-project --no-dev
|
||
|
||
# 安装项目本身和开发依赖
|
||
RUN uv sync --frozen
|
||
|
||
# 设置启动命令
|
||
CMD ["uv", "run", "python", "src/main.py"]
|
||
```
|
||
|
||
---
|
||
|
||
## 第十章：总结与资源
|
||
|
||
### 10.1 uv 的核心优势
|
||
|
||
经过这段时间的使用，我总结出 uv 的几大优势：
|
||
|
||
| 优势 | 说明 | 对比工具 |
|
||
|------|------|----------|
|
||
| **极速** | 比 pip 快 10-100 倍 | pip |
|
||
| **统一** | 一个工具替代六个 | pip, conda, poetry, pyenv, virtualenv, pipx |
|
||
| **轻量** | 几 MB vs 几百 MB | conda |
|
||
| **现代** | 符合 PEP 标准，支持 PEP 621 | poetry |
|
||
| **可靠** | 来自 Astral 公司，ruff 的开发者 | - |
|
||
| **简单** | 命令简洁，容易上手 | conda |
|
||
|
||
### 10.2 迁移指南
|
||
|
||
**从 pip 迁移**
|
||
|
||
uv 的 `pip` 子命令和 pip 完全兼容，你可以直接替换：
|
||
|
||
```powershell
|
||
# 替代 pip install
|
||
uv pip install requests
|
||
|
||
# 替代 pip uninstall
|
||
uv pip uninstall requests
|
||
|
||
# 替代 pip freeze
|
||
uv pip freeze > requirements.txt
|
||
|
||
# 替代 pip list
|
||
uv pip list
|
||
```
|
||
|
||
**从 conda 迁移**
|
||
|
||
```powershell
|
||
# 替代 conda create
|
||
uv venv --python 3.11
|
||
|
||
# 替代 conda activate
|
||
.venv\Scripts\Activate.ps1
|
||
|
||
# 替代 conda install
|
||
uv pip install requests
|
||
|
||
# 替代 conda env export
|
||
uv pip freeze > requirements.txt
|
||
```
|
||
|
||
迁移非常简单，不需要改变任何工作习惯。
|
||
|
||
### 10.3 常见问题
|
||
|
||
**Q: uv 会和 pip 冲突吗？**
|
||
|
||
不会。uv 只是 pip 的替代品，不影响 pip 的使用。你可以在同一个项目中同时使用 pip 和 uv（虽然不推荐）。
|
||
|
||
**Q: 我的现有项目能用 uv 吗？**
|
||
|
||
能。直接在项目目录使用 `uv pip install -r requirements.txt` 即可，uv 兼容 pip 的所有功能。
|
||
|
||
**Q: uv 支持 Windows 吗？**
|
||
|
||
完全支持，而且在 Windows 上性能很好。
|
||
|
||
**Q: uv 支持 Linux/macOS 吗？**
|
||
|
||
支持。uv 支持所有主流平台。
|
||
|
||
**Q: uv 支持私有仓库吗？**
|
||
|
||
支持。你可以通过 `--index-url` 或配置文件指定私有 PyPI 仓库：
|
||
|
||
```toml
|
||
[[tool.uv.index]]
|
||
url = "https://private.pypi.org/simple/"
|
||
```
|
||
|
||
**Q: uv 能管理全局 Python 环境吗？**
|
||
|
||
可以，但不推荐。uv 主要用于项目级别的环境管理。全局 Python 建议使用系统包管理器或 pyenv。
|
||
|
||
### 10.4 学习资源
|
||
|
||
**官方资源**
|
||
|
||
- 官方文档：https://docs.astral.sh/uv/
|
||
- GitHub 仓库：https://github.com/astral-sh/uv
|
||
- Discord 社区：https://discord.gg/astral-sh
|
||
|
||
**社区资源**
|
||
|
||
- Blog：https:// astral.sh/blog/
|
||
- Twitter：@astral_sh
|
||
- GitHub Discussions
|
||
|
||
### 10.5 结束语
|
||
|
||
使用 uv 几个月来，我的 Python 开发体验提升显著。以前要等几十秒的包安装，现在几秒搞定；以前要管理 pip、conda、virtualenv 多个工具，现在一个 uv 全部搞定。
|
||
|
||
如果你还在用 pip 或 conda，我强烈建议你试试 uv。它不会改变你的工作方式，但会让你的工作快很多。
|
||
|
||
当然，工具没有最好的，只有最适合的。uv 适合你，就用；不适合，继续用 pip 也没问题。重要的是找到适合自己的工作方式。
|
||
|
||
---
|
||
|
||
## 附录：命令速查表
|
||
|
||
### 安装与配置
|
||
|
||
| 操作 | 命令 |
|
||
|------|------|
|
||
| 安装 uv（PowerShell） | `irm https://astral.sh/uv/install.ps1 \| iex` |
|
||
| 安装 uv（scoop） | `scoop install uv` |
|
||
| 安装 uv（macOS） | `brew install uv` |
|
||
| 安装 uv（Linux） | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
|
||
| 查看版本 | `uv --version` |
|
||
|
||
### 虚拟环境
|
||
|
||
| 操作 | 命令 |
|
||
|------|------|
|
||
| 创建环境 | `uv venv` |
|
||
| 创建指定版本环境 | `uv venv --python 3.11` |
|
||
| 激活环境（PowerShell） | `.venv\Scripts\Activate.ps1` |
|
||
| 激活环境（Bash） | `source .venv/Scripts/activate` |
|
||
| 退出环境 | `deactivate` |
|
||
|
||
### 包管理
|
||
|
||
| 操作 | 命令 |
|
||
|------|------|
|
||
| 安装包 | `uv pip install requests` |
|
||
| 安装多包 | `uv pip install requests numpy` |
|
||
| 指定版本 | `uv pip install "requests>=2.28"` |
|
||
| 从文件安装 | `uv pip install -r requirements.txt` |
|
||
| 卸载包 | `uv pip uninstall requests` |
|
||
| 列出已安装 | `uv pip list` |
|
||
| 导出依赖 | `uv pip freeze > requirements.txt` |
|
||
| 同步依赖 | `uv pip sync requirements.txt` |
|
||
| 升级包 | `uv pip install --upgrade requests` |
|
||
|
||
### Python 版本
|
||
|
||
| 操作 | 命令 |
|
||
|------|------|
|
||
| 列出版本 | `uv python list` |
|
||
| 安装版本 | `uv python install 3.12` |
|
||
| 卸载版本 | `uv python uninstall 3.10` |
|
||
|
||
### 项目管理
|
||
|
||
| 操作 | 命令 |
|
||
|------|------|
|
||
| 初始化项目 | `uv init myproject` |
|
||
| 添加依赖 | `uv add requests` |
|
||
| 添加开发依赖 | `uv add --dev pytest` |
|
||
| 锁定依赖 | `uv lock` |
|
||
| 同步依赖 | `uv sync` |
|
||
| 运行脚本 | `uv run python script.py` |
|
||
| 运行测试 | `uv run pytest` |
|
||
|
||
### 工具管理
|
||
|
||
| 操作 | 命令 |
|
||
|------|------|
|
||
| 临时运行工具 | `uvx black .` |
|
||
| 安装全局工具 | `uv tool install black` |
|
||
| 列出工具 | `uv tool list` |
|
||
| 升级工具 | `uv tool upgrade black` |
|
||
| 卸载工具 | `uv tool uninstall black` |
|
||
|
||
### 缓存
|
||
|
||
| 操作 | 命令 |
|
||
|------|------|
|
||
| 查看缓存目录 | `uv cache dir` |
|
||
| 清理缓存 | `uv cache clean` |
|
||
| 清理未使用缓存 | `uv cache prune` |
|
||
|
||
---
|
||
|
||
**写作日期**：2026 年 4 月
|
||
|
||
**作者**：刘航宇
|
||
|
||
**参考链接**：
|
||
- [uv 官方文档](https://docs.astral.sh/uv/)
|
||
- [uv GitHub 仓库](https://github.com/astral-sh/uv)
|