易易的笔记

告别 pip/venv 碎片化！UV 驱动的 Python 现代项目工作流全教程（基于 pyproject.toml）

·

一块自由的砖 的头像
一块自由的砖

长期以来，Python 开发者饱受 pip + venv + requirements.txt 碎片化工作流的困扰：环境搭建慢、依赖版本混乱、开发/生产依赖无法区分、项目配置无统一标准。如今基于 PEP 标准化的 pyproject.toml 已成 Python 项目标配，而 UV 作为极速一体化工具，彻底重构了 Python 项目开发、依赖管理、环境维护、打包发布的全流程。本文带你从零搭建基于项目的现代化 UV 工作流，吃透 pyproject.toml 核心配置，实现项目标准化、可复现、可维护的工程化开发。

一、为什么要放弃传统工作流？UV 核心优势

1.1 传统工作流的痛点

传统 Python 开发依赖 pip 安装包、venv 创建虚拟环境、requirements.txt 管理依赖，存在诸多硬伤：

  • 配置碎片化：项目元数据、依赖、打包配置分散在多个文件，无统一入口
  • 依赖区分困难：无法原生区分生产依赖与开发依赖，需手动维护多份依赖文件
  • 环境复现不稳定：requirements.txt 仅记录版本，无完整锁版本机制，跨环境安装版本不一致
  • 效率极低：pip 安装、解析依赖速度慢，新项目初始化流程繁琐
  • 不符合现代规范：逐步被 PEP 621、PEP 631 新标准淘汰

1.2 UV + pyproject.toml 现代工作流优势

UV 是由 Astral 团队开发的极速 Python 一体化工具，集成环境管理、依赖解析、打包、运行、脚本执行能力，完全围绕 pyproject.toml 标准构建，核心优势：

  • 极速高效：依赖解析、安装速度比 pip 快 10-100 倍，环境秒级搭建
  • 统一标准化：唯一核心配置文件 pyproject.toml，遵循 PEP 621 官方标准，替代所有零散配置
  • 原生依赖分组：天然支持生产依赖、开发依赖分离，无需手动拆分文件
  • 确定性环境：自动生成 uv.lock 锁文件，保证跨设备、跨团队环境完全一致
  • 零配置开箱即用：自动管理虚拟环境，无需手动创建、激活
  • 全流程闭环：覆盖项目初始化、开发、测试、打包、发布全生命周期

二、UV 安装与环境准备

UV 支持 Windows / macOS / Linux 全平台，提供一键安装命令，无需额外依赖。

2.1 全平台安装命令

Linux / macOS

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

Windows（PowerShell）

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

2.2 验证安装

uv --version

输出版本号即安装成功，后续可通过 uv self update 一键升级 UV。

三、基于 UV 初始化标准 Python 项目

UV 提供 uv init 命令一键生成符合现代规范的项目骨架，自动创建 pyproject.toml、README、入口文件等核心文件。

3.1 初始化新项目

# 创建项目文件夹并进入
mkdir uv-demo-project && cd uv-demo-project

# 一键初始化项目
uv init

3.2 自动生成的项目结构

初始化完成后，目录结构如下（标准现代 Python 项目结构）：

uv-demo-project/
├── .gitignore       # 自动生成 git 忽略文件
├── README.md        # 项目说明文档
├── main.py          # 项目入口文件
└── pyproject.toml   # 项目核心配置文件（重点）

3.3 自动创建虚拟环境

UV 不会默认生成 .venv，在首次添加依赖或执行项目命令时自动创建虚拟环境：

# 安装第一个依赖，自动生成 .venv 和 uv.lock
uv add requests

此时项目会新增 .venv/ 虚拟环境文件夹、uv.lock 全局锁文件。

四、核心精讲：彻底吃透 pyproject.toml 配置

pyproject.toml 是现代 Python 项目的唯一配置入口，替代了传统的 setup.py、setup.cfg、requirements.txt。下文逐字段拆解 UV 项目标准配置，覆盖日常开发 99% 场景。

4.1 基础完整配置模板

初始化后默认配置+常用扩展配置，完整可直接复用：

[project]
# 项目名称（pip/uv 安装、PyPI 发布名称）
name = "uv-demo-project"
# 项目版本（语义化版本规范）
version = "0.1.0"
# 项目简短描述
description = "UV 现代 Python 工作流演示项目"
# 详细说明文档路径
readme = "README.md"
# 支持的 Python 版本（严格限制环境）
requires-python = ">=3.11"
# 项目许可证
license = { file = "LICENSE" }
# 作者信息
authors = [
  { name = "Your Name", email = "your@email.com" }
]
# 生产环境核心依赖
dependencies = [
  "requests>=2.31.0"
]

[dependency-groups]
dev = ["mypy>=2.1.0", "pytest>=9.0.3", "ruff>=0.15.14"]
# UV 专属配置（环境、解析、行为配置）
[tool.uv]
# 不自动生成 __pycache__ 
compile-bytecode = false 
# Ruff 代码格式化/检查配置
[tool.ruff]
line-length = 120 
target-version = "py311" 
# Pytest 测试配置
[tool.pytest.ini_options]
testpaths = ["tests"] 
python_files = "test_*.py"

4.2 核心字段逐行详解

4.2.1 [project] 基础元数据（PEP 621 标准）

  • name：项目唯一标识，用于包安装、导入、发布，必须小写、无空格
  • version：语义化版本，遵循 主版本.次版本.修订号，用于版本迭代管理
  • requires-python：限制项目运行的 Python 最低版本，避免版本不兼容问题
  • dependencies：生产依赖，项目运行必需的第三方库，UV 会自动解析版本兼容关系

4.2.2 依赖分组：区分生产/开发依赖

[dependency-groups] 是现代工作流的核心，彻底解决传统依赖混杂问题：

  • 开发依赖：dev 分组配置，仅用于代码检查、测试、格式化，生产环境不安装

4.2.3 [tool.xxx] 工具专属配置

所有第三方工具配置统一收纳在 [tool.xxx] 下，UV、Ruff、Pytest、Mypy 等均支持，实现一单配置，全局生效，无需分散多个配置文件。

4.3 关键文件：uv.lock 锁文件作用

执行 uv add / uv sync 后自动生成 uv.lock：

  • 记录所有依赖的精确版本、哈希值、依赖树
  • 保证团队协作、服务器部署、本地开发环境100% 版本一致
  • 必须提交到 Git 仓库，是项目可复现的核心保障

五、UV 日常项目工作流实操（全生命周期）

掌握配置后，熟练使用以下命令，即可完成项目全日常运维，彻底替代 pip/venv。

5.1 依赖管理（核心操作）

5.1.1 添加依赖

# 添加生产依赖（自动写入 pyproject.toml dependencies）
uv add 包名
uv add requests numpy

# 添加开发依赖（自动写入 dev 分组）
uv add --dev pytest ruff mypy

5.1.2 删除依赖

# 删除生产/开发依赖，自动更新配置和锁文件
uv remove 包名

5.1.3 同步环境（多人协作/换设备必备）

拉取项目代码后，无需手动安装依赖，一键同步完整环境：

# 根据 pyproject.toml + uv.lock 精准还原环境
uv sync

# 仅同步生产依赖（部署环境使用）
uv sync --no-dev

5.2 虚拟环境管理

UV 自动管理 .venv，无需手动创建，常用操作：

# 手动创建/重建虚拟环境
uv venv

# 激活环境（Linux/macOS）
source .venv/bin/activate

# 激活环境（Windows）
.venv\Scripts\activate

# 退出环境
deactivate

💡 小贴士：UV 支持无需激活环境直接运行，通过 uv run 自动调用当前项目虚拟环境：

uv run python main.py
uv run pytest
uv run ruff check

5.3 项目打包与发布

UV 原生支持打包，无需 setuptools，一键生成标准安装包：

# 生成 sdist 源码包 + wheel 二进制包
uv build

# 发布到 PyPI
uv publish

六、旧项目迁移：从 requirements.txt 迁移到 UV

针对传统旧项目，一键迁移至现代 UV 工作流，无需重构代码：

# 1. 初始化 uv 项目
uv init

# 2. 从 requirements.txt 导入生产依赖
uv add -r requirements.txt

# 3. 从 dev-requirements.txt 导入开发依赖
uv add --dev -r dev-requirements.txt

# 4. 同步环境，生成 lock 文件
uv sync

迁移完成后，即可删除老旧的requirements.txt 系列文件，统一使用 pyproject.toml 管理。

七、UV 项目最佳实践

  1. 严格区分依赖分组：业务依赖放生产组，工具依赖放开发组，部署时使用 uv sync --no-dev 精简环境
  2. 强制提交 lock 文件：团队协作项目必须提交 uv.lock，保证环境一致性
  3. 遵循语义化版本：严格按照 主.次.修 规则迭代项目版本
  4. 统一工具配置：所有代码检查、格式化、测试工具配置全部写入 pyproject.toml，不使用零散配置文件
  5. 定期更新依赖：使用 uv update 批量更新依赖，配合 lock 文件保证稳定性
  6. 忽略 .venv 目录：在 .gitignore 中配置忽略虚拟环境文件夹，仅保留配置文件

其他文章