プロジェクト管理したい（pyproject.toml）

[project]
name = "PyPIに公開するプロジェクト名"
version = "..."
description = "..."
readme = "README.md"
requires-python = ">=3.10"
authors = [
    {name = "qumasan", email = "..."}
]
license = { text = "MIT" }
keywords = ["...", "..."]
dependencies = [
    "pydantic",
    "typer",
    "rich",
    "loguru",
]

[project.optional-dependencies]
docs = [
    "zensical",
]

dev = [
    "pytest",
    "pytest-cov",
    "ruff",
    "commitizen",
    "pre-commit",
]

[project.scripts]
script_name = "..."

[project.urls]
Repository = "..."
Documentation = "..."
Issues = "..."

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

[tool.uv]
managed = true

[tool.ruff]
line-length = 100
target-version = "py312"

[tool.commitizen]
name = "cz_conventional_commits"
tag_format = "$version"
version_scheme = "semver2"
version_provider = "uv"
update_changelog_on_bump = true
major_version_zero = true
version_files = [
    "..."
]

pyproject.tomlは、Pythonプロジェクトの設定を一元管理するための標準ファイルです。 パッケージ情報、依存関係、ツール設定、ビルド設定などを一箇所にまとめて書くことができます。

注釈

長い間、Pythonのプロジェクト設定は、setup.pyやsetup.cfg、requirements.txtなどに分散して、正しい書き方を探すのが大変でした。

2016年のPEP 518でpyproject.tomlが導入され、 2018年に登場したpoetryが採用したことで、デファクトスタンダードとして使われるようになりました。

その後、 PEP 517（ビルドバックエンドの標準化）、 PEP 621（[project]メタデータの標準化） が策定され、uvやhatchなどモダンなツールの登場により標準化が進みました。

注釈

2016年の段階でTOML形式の設定ファイルが導入されたのは不思議だったなぁと思っています。 当時のPythonの標準ライブラリにはTOMLパーサーが含まれておらず、tomliやtomllibなどの外部ライブラリが必要でした。 またTOML形式の仕様も固まってない時期です。

そのため、自作ツールの設定は、まだまだINI形式やYAML形式で書く方が簡単で、結局、設定ファイルが2つに増えた印象でした。 2022年のPython 3.11で、ようやく標準ライブラリにTOMLパーサーが含まれるようになりました。

プロジェクト設定したい（[project]）

[project]
name = "PyPIに公開するプロジェクト名"
version = "..."
description = "..."
readme = "README.md"
requires-python = ">=3.10"
authors = [
    {name = "qumasan", email = "..."}
]
license = { text = "MIT" }
keywords = ["...", "..."]

[project]テーブルに、プロジェクトのメタデータを書きます。 PEP 621で必須とされているのはnameだけです。 versionも必須ですが、dynamic = ["version"]と書けば、 ビルドツール側に動的に決定させることもできます（commitizenやhatch versionなどと組み合わせる場合に便利です）。 それ以外のdescription、readme、authors、license、keywordsはすべて任意です。

カテゴリーしたい（classifiers）

[project]
classifiers = [
    "Development Status :: 3 - Alpha",
    "Intended Audience :: Science/Research",
    "License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.12",
]

[project]テーブルのclassifiersに、PyPIで規定されている定型のカテゴリー文字列（Trove classifiers）を書けます。 開発状況、対象ユーザー、ライセンス、対応Pythonバージョンなどを、PyPIのプロジェクトページで検索・絞り込みできるようにする分類です。 書式が自由なkeywordsと違い、 公式の一覧 から選んで書く必要があります。

依存パッケージしたい（dependencies）

[project]
dependencies = [
    "pydantic",
    "typer",
    "rich",
    "loguru",
]

[project]テーブルのdependenciesキーに、プロジェクトの実行に必要な依存パッケージを書きます。 バージョン指定する場合は "pydantic>=2.0" のように、PEP 508形式の文字列で書きます。

オプション依存パッケージしたい（[project.optional-dependencies]）

[project.optional-dependencies]
docs = [
    "zensical",
]

dev = [
    "pytest",
    "pytest-cov",
    "ruff",
    "commitizen",
    "pre-commit",
]

インストール時に選択できる、追加の依存パッケージ群を定義します。 キーがextra名（docs、devなど）、値がその依存パッケージの配列です。 利用者はpip install my-project[docs]のように、extra名を指定してインストールできます。

devのように開発専用のツールをここに置くこともできますが、 配布先（PyPIなど）にextraとして公開される点に注意してください。 CI/CD専用など、パッケージの利用者に見せる必要のない依存は、 uvやpoetryが対応する[dependency-groups]（PEP 735）で管理する方が適切です。

関連リンクしたい（[project.urls]）

[project.urls]
Repository = "https://gitlab.com/osechi/kazunoko"
Documentation = "https://kazunoko.readthedocs.io"
Issues = "https://gitlab.com/osechi/kazunoko/-/issues"

[project.urls]テーブルに、プロジェクト関連のリンクをまとめて書けます。 キーは自由に決められますが、 Repository（ソースコード）、 Documentation（ドキュメント）、 Homepage（公式サイト）、 Issues（課題管理） あたりがよく使われます。 PyPIのプロジェクトページに、サイドバーのリンクとして表示されます。

コマンド名したい（[project.scripts]）

[project.scripts]
cli-name = "module.path:app"  # src/module/path.pyのapp関数

[project.scripts]で、コマンド名を設定できます。 左辺のcli-nameがコマンド名、 右辺が実行する関数です。 モジュールまでのパスは.で区切り、 モジュール内の関数は:で区切ります。 module.path:appは、src/module/path.pyのapp()関数を指します。

ビルド環境したい（[build-system]）

[build-system]で、パッケージをビルドするためのツール（ビルドバックエンド）を指定できます。 requiresに必要なパッケージ、build-backendにビルド処理を担うモジュールを書きます（PEP 517、PEP 518）。 使っているプロジェクト管理ツールに合わせて選びます。

hatchしたい（hatchling）

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

hatchのビルドバックエンドです。 hatch newで作成したプロジェクトでは、デフォルトでこの設定になります。

poetryしたい（poetry-core）

[build-system]
requires = ["poetry-core>=2.0.0,<3.0.0"]
build-backend = "poetry.core.masonry.api"

poetryのビルドバックエンドです。 poetry newやpoetry initで作成したプロジェクトでは、デフォルトでこの設定になります。

uvしたい（uv_build）

[build-system]
requires = ["uv_build>=0.12.5,<0.13.0"]
build-backend = "uv_build"

uvのビルドバックエンドです。 uv initで作成したプロジェクトでは、デフォルトでこの設定になります。 requiresのバージョン範囲は、インストールされているuvのバージョンに合わせて自動で設定されます。

注釈

uvはプロジェクト管理ツールであり、ビルドバックエンドとは独立した仕組みです。 [build-system]をhatchlingなど他のバックエンドに書き換えても、 uv buildやuv syncは問題なく動作します。

flitしたい（flit_core）

[build-system]
requires = ["flit_core>=3.11,<5"]
build-backend = "flit_core.buildapi"

シンプルな単一パッケージの配布に特化したflitのビルドバックエンドです。 複雑な設定を必要としない、小規模なプロジェクトに向いています。

setuptoolsしたい（setuptools）

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

古くから使われているsetuptoolsのビルドバックエンドです。 [build-system]テーブル自体を省略した場合も、フォールバックとしてsetuptoolsが使われます。

それぞれの特徴

バックエンド	特徴	C拡張
hatchling	プラグインが豊富で設定の柔軟性が高い	プラグイン経由
poetry-core	poetryと一体で、依存関係管理に強い	未対応
uv_build	最速・ゼロコンフィグ志向	非対応
flit_core	最小限・軽量、設定項目が少ない	非対応
setuptools	もっとも枯れていて実績が豊富	標準対応

生成されるwheel・sdistはどのバックエンドでも標準形式（PEP 517・PEP 427）なので、 pip installする利用者側は違いを意識する必要はありません。 一方、[tool.poetry.*]や[tool.hatch.*]のようなツール固有の設定は共通化されていないため、 バックエンドを乗り換える際は書き直しが必要になることがあります。

C拡張やCythonなど、コンパイルが必要なパッケージを作る場合はsetuptoolsを選ぶのが無難です。 それ以外の純粋なPythonパッケージであれば、使っているプロジェクト管理ツール純正のバックエンドを選ぶと摩擦が少ないです。

ツール設定したい（tool.ツール名）

[tool.uv]
managed = true

[tool.ツール名]テーブルに、各ツール独自の設定を書きます。 [project]や[build-system]と違って標準化されておらず、書式や項目はツールごとに異なります。 [tool.uv]はuvの設定です。 managed = true（デフォルト）で、このプロジェクトをuvが管理していることを明示します。

[tool.ruff]
line-length = 100
target-version = "py312"

[tool.ruff]はRuffの設定です。 line-lengthで1行の最大文字数、target-versionで対象のPythonバージョンを指定できます。

[tool.commitizen]
name = "cz_conventional_commits"
version_provider = "pep621"
tag_format = "v$version"

[tool.commitizen]はcommitizenの設定です。 version_providerで、バージョン番号をどこから読み書きするか指定します。 "pep621"を指定すると、[project]のversionキーと連動します。

注釈

[tool.hatch.build.targets.wheel]のように、ツール名の下にさらに階層を作ることもできます。 どんなキーが使えるかは、それぞれのツールの公式ドキュメントを参照してください。

パッケージ名とコマンド名を別々にしたい

[project]
name = "osechi-kazunoko"

[project.scripts]
kazunoko = "kazunoko.cli:app"  # src/kazunoko/cli.pyのapp関数

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

[tool.hatch.build.targets.wheel]
packages = ["src/kazunoko"]

パッケージ名とコマンド名を別々に設定することで、 PyPIで配布するパッケージ名の衝突を避けつつ、 ユーザーが実行するコマンド名を短く設定できます。

しかし、実際に設定してみようとしたら、少し躓いたので整理しました。

上記は、 パッケージ名をosechi-kazunokoとして、 コマンド名をkazunokoとして設定した例です。

[project]のnameにパッケージ名を、 [project.scripts]のキーにコマンド名を設定します。

躓いたのは[build-system]の設定でした。 uv_buildではうまくいかず、hatchlingを指定し、 さらに [tool.hatch.build.targets.wheel]のpackagesに、パッケージのソースが入っているディレクトリ名 （この例ではsrc/kazunoko）の設定が必要でした。

コマンドを一時的に実行する場合は uvx --from osechi-kazunoko kazunoko と打てばOKです。