项目初始化与 pyproject.toml

uv init 做了什么？

一句 uv init 看似轻描淡写，它为你生成了一个符合所有现代 Python 标准的项目骨架。

$ uv init myapp
Initialized project `myapp` at `/home/user/myapp`

$ tree myapp
myapp/
├── .python-version      # 固定 Python 版本（默认当前 uv 默认版本）
├── .gitignore           # 包含 .venv, __pycache__ 等
├── README.md            # 空 README
├── main.py              # 入口文件
└── pyproject.toml       # 核心配置

uv init 的四种模式

pyproject.toml 逐段解读

pyproject.toml 是 PEP 518（2016）和 PEP 621（2020）确立的 Python 项目统一配置文件，取代了历史上的 setup.py、setup.cfg、Pipfile、requirements.txt 等。下面是一个典型的完整示例：

[project]
name = "myapp"
version = "0.1.0"
description = "A modern Python app powered by uv"
readme = "README.md"
requires-python = ">=3.12"
authors = [
  { name = "Alice", email = "alice@example.com" }
]
license = { text = "MIT" }
keywords = ["web", "api"]
classifiers = [
  "Programming Language :: Python :: 3",
  "License :: OSI Approved :: MIT License",
]
dependencies = [
  "fastapi>=0.110",
  "uvicorn[standard]>=0.29",
  "httpx",
]

[project.optional-dependencies]
# 用户可选安装：pip install myapp[postgres]
postgres = ["asyncpg>=0.29"]
redis = ["redis>=5"]

[dependency-groups]
# PEP 735 —— uv 原生支持的开发分组
dev = [
  "pytest>=8",
  "pytest-asyncio",
  "ruff",
  "mypy",
]
docs = ["mkdocs-material"]

[project.scripts]
# 安装后生成 CLI 命令
myapp = "myapp.cli:main"

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.uv]
# uv 专属配置
managed = true
default-groups = ["dev"]

[project] 核心字段详解

dependency-groups：uv 强烈推荐的新方式

传统做法把开发依赖塞进 [project.optional-dependencies].dev，但这在语义上是错的——dev 不是"用户可选安装"，而是"开发者专用"。PEP 735 新增的 [dependency-groups] 解决了这个混淆，uv 是第一个原生支持的工具。

[dependency-groups]
dev = ["pytest", "ruff"]
test = ["pytest-cov", "hypothesis"]
docs = ["mkdocs", "mkdocs-material"]

# 分组可以互相包含
ci = [{ include-group = "test" }, "coverage[toml]"]

# 只装默认组（default-groups 配置里的，默认是 dev）
uv sync

# 装特定组
uv sync --group docs

# 生产部署：完全不装开发组
uv sync --no-dev
# 或
uv sync --only-group main

[tool.uv] — uv 专属配置

虽然大多数字段都是 PEP 标准，uv 也有一些扩展配置放在 [tool.uv] 里：

[tool.uv]
# 启用项目模式（默认 true，关闭则退化为 pip 兼容模式）
managed = true

# 默认同步哪些依赖组
default-groups = ["dev"]

# 依赖覆盖：强制使用特定版本（绕过子依赖声明）
override-dependencies = ["urllib3<2"]

# 约束：不强制安装，但若安装则必须满足
constraint-dependencies = ["setuptools>=68"]

# 对不完整元数据包的回退策略
resolution = "highest"  # highest / lowest / lowest-direct

# 在项目中自动管理的 Python 版本
python-preference = "managed"  # managed / system / only-managed / only-system

# 可编辑安装（开发模式）
[tool.uv.sources]
# 把某个依赖指向本地路径/git/workspace
mylib = { path = "../mylib", editable = true }
fastapi = { git = "https://github.com/tiangolo/fastapi", rev = "master" }

[build-system] — 构建后端选择

如果你的项目要打包发布（uv build），必须配置 build-system。uv 本身不是构建后端，只是调用你选的后端。

目录布局：flat vs src

myapp/
├── pyproject.toml
├── main.py
└── myapp/
    ├── __init__.py
    └── ...

mylib/
├── pyproject.toml
└── src/
    └── mylib/
        ├── __init__.py
        └── ...

[project.scripts] — 生成 CLI 命令

[project.scripts]
myapp = "myapp.cli:main"
myapp-admin = "myapp.admin:cli"

[project.gui-scripts]  # Windows 下不开控制台窗口
myapp-gui = "myapp.gui:run"

[project.entry-points."myapp.plugins"]  # 插件系统
csv = "myapp.plugins.csv_backend:Plugin"

安装项目后（uv sync），这些命令会自动出现在 venv 的 .venv/bin/ 下。uv run myapp 即可直接调用。

动态字段（dynamic）

有时候你希望 version、readme 等字段从代码/文件自动读取，而不是硬编码。用 dynamic 声明：

[project]
name = "myapp"
dynamic = ["version"]

[tool.hatch.version]
path = "src/myapp/__init__.py"  # 从代码读 __version__