从零开始掌握 uv：新一代超快 Python 项目与包管理器（含 Windows 支持） - 实践

从零开始掌握 uv：新一代超快 Python 项目与包管理器（含 Windows 支持）

在 Python 开发的世界里，包管理长期以来是一个“碎片化”的领域：pip 用于安装、virtualenv 用于环境隔离、pip-tools 用于依赖锁定、poetry 或 rye 用于项目管理、pipx 用于工具安装……每个工具都有自己的配置方式和使用习惯，初学者常常感到困惑，而资深开发者也疲于在不同工具间切换。

2024 年，Astral 团队（Ruff 的作者）带来了一个革命性的解决方案：uv —— 一个用 Rust 编写的、极速的 Python 包与项目管理器。它不仅快如闪电（比 pip 快 10–100 倍），还试图统一整个 Python 工具链。本文将带你由浅入深，从安装到实战，全面掌握 uv 的核心能力，并特别包含 Windows 环境下的完整操作指南。

---

一、什么是 uv？为什么值得关注？

uv 是一个开源的 Python 工具链替代品，目标是“一个工具，搞定一切”。它集成了以下工具的功能：

• pip：安装包
• pip-tools：生成 lockfile
• virtualenv：创建虚拟环境
• poetry / rye：项目依赖管理
• pipx：安装和运行 CLI 工具
• pyenv：管理 Python 版本（实验性支持）
• twine：发布包

更令人惊叹的是性能：在缓存命中的情况下，安装像 trio 这样的复杂依赖，uv 比 pip 快数十倍。这一切得益于其用 Rust 编写的核心，以及精心设计的全局缓存机制，实现依赖去重，节省磁盘空间。

uv 支持 macOS、Linux 和 Windows，并且无需预先安装 Rust 或 Python。

---

二、Windows 下安装 uv

方法一：使用 PowerShell 安装（推荐）

1. 以管理员身份打开 PowerShell（非必需，但可避免权限问题）。
2. 执行官方安装脚本：

irm https://astral.sh/uv/install.ps1 | iex

运行结果：

Downloading uv 0.8.22 (x86_64-pc-windows-msvc)                                                                          Installing to C:\Users\DELL\.local\binuv.exeuvx.exeuvw.exe
everything's installed!
To add C:\Users\DELL\.local\bin to your PATH, either restart your shell or run:set Path=C:\Users\DELL\.local\bin;%Path%   (cmd)$env:Path = "C:\Users\DELL\.local\bin;$env:Path"   (powershell)

irm 是 Invoke-RestMethod 的缩写，iex 是 Invoke-Expression 的缩写。

3. 安装完成后，重启终端（或执行 refreshenv，如果你安装了 scoop 或 chocolatey），使 PATH 生效。

4. 验证安装：

uv --version

你应该看到类似输出：uv 0.5.0 (a1b2c3d4 2025-09-29)
运行结果：

C:\Users\DELL>uv --version
uv 0.8.22 (ade2bdbd2 2025-09-23)

方法二：通过 pip 安装（如果你已有 Python）

pip install uv

⚠️ 注意：这种方式安装的 uv 依赖于当前 Python 环境，性能略逊于原生二进制版本，但功能完全一致。

方法三：手动下载（适用于离线环境）

1. 访问 uv GitHub Releases
2. 下载适用于 Windows 的压缩包（如 uv-windows-x86_64.zip）
3. 解压后将 uv.exe 所在目录加入系统 PATH 环境变量

---

三、Windows 下快速上手：创建并运行项目

1. 初始化项目

D:\python_projects>uv init uv_demo
Initialized project `uv-demo` at `D:\python_projects\uv_demo`

这会生成：

• pyproject.toml（项目元数据）
• .gitignore
• README.md
• src/myproject/__init__.py

D:\python_projects>cd uv_demo
D:\python_projects\uv_demo>dir驱动器 D 中的卷是 新加卷卷的序列号是 66C3-87A8D:\python_projects\uv_demo 的目录
2025/09/29  21:46              .
2025/09/29  21:46              ..
2025/09/29  21:46                 5 .python-version
2025/09/29  21:46                85 main.py
2025/09/29  21:46               153 pyproject.toml
2025/09/29  21:46                 0 README.md4 个文件            243 字节2 个目录 299,954,900,992 可用字节

2. 添加依赖

D:\python_projects\uv_demo>uv add requests
Using CPython 3.11.5 interpreter at: D:\python311\python.exe
Creating virtual environment at: .venv
Resolved 6 packages in 8.94s
Prepared 5 packages in 4.87s
░░░░░░░░░░░░░░░░░░░░ [0/5] Installing wheels...                                                                         warning: Failed to hardlink files; falling back to full copy. This may lead to degraded performance.
If the cache and target directories are on different filesystems, hardlinking may not be supported.
If this is intentional, set `export UV_LINK_MODE=copy` or use `--link-mode=copy` to suppress this warning.
Installed 5 packages in 17ms
+ certifi==2025.8.3
+ charset-normalizer==3.4.3
+ idna==3.10
+ requests==2.32.5
+ urllib3==2.5.0

uv 会自动：

• 在当前目录创建 .venv 虚拟环境（无需手动激活）
• 解析并安装 requests 及其依赖
• 更新 pyproject.toml 和 uv.lock

输出示例（Windows 下同样极速）：

Resolved 5 packages in 210ms
Prepared 5 packages in 480ms
Installed 5 packages in 2ms+ requests==2.32.3+ myproject==0.1.0

3. 运行代码

创建 /uv_demo/main.py：

def main():
print("Hello from uv-demo!")
import requests
print("Status:", requests.get("https://httpbin.org/status/200").status_code)
if __name__ == "__main__":
main()

然后运行：

D:\python_projects\uv_demo>uv run python -m main

✅ 注意：Windows 下无需担心路径分隔符或激活脚本，uv run 自动处理一切。

Hello from uv-demo!
Status: 200

---

四、Windows 特别提示

虚拟环境位置

uv 默认在项目根目录下创建 .venv 文件夹（与 poetry 行为一致），你可以在 Windows 资源管理器中直接看到它。

脚本模式（Script Mode）在 Windows 同样可用

echo 'import requests; print(requests.get("https://astral.sh"))' > example.py
uv add --script example.py requests
uv run example.py

uv 会为该脚本自动创建隔离环境，无需管理员权限，也不会污染全局 Python。

工具运行（uvx）

再运行一个pycowsay工具：

D:\python_projects\uv_demo>uvx pycowsay "Hello from Windows!"-------------------
< Hello from Windows! >-------------------\   ^__^\  (oo)\_______(__)\       )\/\||----w |||     ||

首次运行会自动下载并缓存，后续调用几乎瞬时完成。

与 Windows Terminal / VS Code 集成

• 在 VS Code 中打开项目后，选择解释器时可指向 .venv\Scripts\python.exe
• uv run 命令可直接在 VS Code 终端中使用，无需额外配置

---

五、核心功能（跨平台通用）

以下功能在 Windows、macOS、Linux 上行为一致：

1. 项目依赖管理

• uv lock：生成 uv.lock
• uv sync：根据 lockfile 同步环境
• 支持 Cargo-style workspaces（多包项目）

2. 兼容 pip

uv pip install numpy pandas

可直接替换现有工作流，获得性能提升。

3. 构建与发布

uv build      # 生成 .tar.gz 和 .whl
uv publish    # 上传到 PyPI

---

六、为什么选择 uv？（尤其对 Windows 用户）

• ✅ 无需 WSL：原生支持 Windows，性能不打折
• ✅ 告别 venv\Scripts\activate.bat：uv run 自动处理环境
• ✅ 安装简单：一行 PowerShell 命令搞定
• ✅ 极速体验：即使在 NTFS 文件系统上，依然比 pip 快一个数量级
• ✅ 节省空间：全局缓存避免重复下载（缓存位于 %LOCALAPPDATA%\uv）

---

七、结语

uv 正在重新定义 Python 的开发体验，无论你使用的是 Windows、macOS 还是 Linux。对于长期被 Python 工具链“割裂”困扰的 Windows 开发者来说，uv 提供了一个统一、快速、可靠的解决方案。

现在就打开 PowerShell，试试这个改变游戏规则的工具吧：

irm https://astral.sh/uv/install.ps1 | iex
uv init hello-uv
cd hello-uv
uv add rich
echo "import rich; rich.print('✨ Hello from uv on Windows!')" > demo.py
uv run python demo.py

未来已来，而它快得惊人。

---

参考资料：

• uv 官方文档
• uv Installation Guide
• uv on Windows FAQ（社区整理）