python uv 管理包和项目

Python 包管理的新纪元：uv 全指南

在 Python 社区中，包管理一直是个让人头疼的问题。从传统的 pip 到 pip-tools，再到复杂的 poetry 和 pyenv，各有千秋但也各有痛点。直到 uv 的出现——这个由 Rust 编写、速度快到令人发指的工具，正在统一 Python 的开发流程。

---

一、 安装与环境准备

uv 的设计理念是“单文件、零依赖”。

1. 快速安装

• Windows (PowerShell):

  PowerShell

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

• macOS/Linux:

  Bash

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

2. 自动管理 Python 版本

uv 可以直接帮你下载 Python 解释器，无需再额外安装 pyenv 或去官网下载：

Bash

uv python install 3.12          # 安装指定版本
uv python list                 # 查看可用版本

---

二、 基础使用：从零开始一个项目

uv 强推“项目制”工作流，不再需要你手动去激活虚拟环境。

1. 初始化

Bash

uv init my-project
cd my-project

这会生成 pyproject.toml 和 .python-version 文件。

2. 管理依赖

• 添加依赖： uv add requests
• 添加开发依赖： uv add --dev pytest
• 删除依赖： uv remove requests
• 同步环境： uv sync (根据配置文件强制将本地环境调整为一致)

3. 运行项目

你甚至不需要执行 source .venv/bin/activate。直接运行：

Bash

uv run main.py

uv 会自动在 .venv 中执行代码。如果环境没创建，它会自动创建并安装依赖。

---

三、 复杂使用：进阶技巧

1. 运行单文件脚本（无需项目）

如果你只有一个 script.py，但它依赖 pandas，你可以直接运行：

Bash

uv run --with pandas script.py

uv 会在临时环境中安装 pandas 并执行，运行完即焚，保持系统整洁。

2. 使用 uvx 运行工具

类似于 Node.js 的 npx，可以不安装包而直接运行其命令：

Bash

uvx ruff check .       # 使用 ruff 检查代码
uvx textual-paint      # 运行一个终端画板小工具

3. 依赖分组 (Dependency Groups)

根据最新的 PEP 735，uv 支持将依赖分组管理（如 dev、docs、test）：

Bash

uv add --group docs mkdocs

---

四、 常见配置与避坑指南

1. 网络与国内源配置

在中国开发，网络往往是最大的障碍。可以在项目根目录创建 uv.toml 或在 pyproject.toml 中配置：

Ini, TOML

[[tool.uv.index]]
name = "aliyun"
url = "https://mirrors.aliyun.com/pypi/simple/"
default = true

2. 403 Forbidden 或超时错误

• 403 错误： 通常是镜像源（如清华源）触发了流量保护。建议切换至阿里云或腾讯云。

• 超时： uv 下载极快，如果网络波动，可以调高超时时间：

  PowerShell

  $env:UV_HTTP_TIMEOUT = 120

3. 代理设置

uv 遵循标准环境变量：HTTP_PROXY 和 HTTPS_PROXY。

---

五、 文件作用解析：它们都是干什么的？

文件 / 文件夹	作用	是否提交到 Git
pyproject.toml	项目的核心配置文件，定义依赖、元数据和工具配置。	是
uv.lock	锁定文件。精确记录每个包的版本和哈希值，确保团队环境一致。	是
.python-version	指定该项目使用的 Python 版本。	是
.venv/	存放 Python 解释器和已安装包的物理目录。	否
uv.toml	(可选) uv 的专项配置文件，如设置镜像源、并发限制等。	是

---

六、 为什么选择 uv？

1. 快： 底层 Rust 编写，带全局缓存，安装过的包在第二个项目中瞬间“链接”完成。
2. 全： 一个工具顶替了 pip、venv、pyenv、pip-tools。
3. 稳： uv.lock 提供了比传统 requirements.txt 更可靠的复现性。

---

希望这篇文章能帮你快速上手这个 Python 开发者的神器！如果你正在寻找一个能让你从环境泥潭中解脱出来的方案，uv 就是唯一的答案。