pyproject.tomlとは？これからのPythonプロジェクト管理入門

Pythonを学び始めると、最初は.pyファイルを書くだけで十分です。けれど慣れてくると、仮想環境、ライブラリ管理、テスト、コード整形など、管理するものが増えてきます。

そこで登場するのがpyproject.tomlです。名前だけ見ると少し難しそうですが、役割はとてもシンプルで、Pythonプロジェクトの設定をまとめて書くためのファイルです。

私自身、エンジニアとして10年ほどPythonを使ってきました。昔は設定ファイルがあちこちに散らばり、プロジェクトを引き継いだ瞬間に、まず設定ファイル探しから始まることも珍しくありませんでした。

最近はpyproject.tomlを中心に管理する流れが一般的です。初心者のうちに知っておくと、実務のコードを読むときにもかなり楽になります。

この記事では、IT初心者の方でもわかるように、役割、基本的な書き方、設定例、実務での注意点まで順番に解説します。

pyproject.tomlとは¶

pyproject.tomlとは、Pythonプロジェクトの設定情報を書くためのファイルです。公式ドキュメントでも、ビルド設定やプロジェクト情報、各種ツール設定を記述するファイルとして扱われています。

やさしく言うと、プロジェクトの説明書のようなものです。名前、Pythonバージョン、必要なライブラリ、開発ツールの設定をまとめておけます。

たとえば、次のような情報を書けます。

これまでPythonでは、設定を別々のファイルに書くことが多くありました。requirements.txtにはライブラリ、pytest.iniにはテスト設定、というような形です。

もちろん今でもそれぞれ使われています。ですが、設定が増えるほど初心者には全体像が見えにくくなります。

pyproject.tomlは、バラバラになりがちな設定を1つの入口にまとめる存在です。

なぜpyproject.tomlが必要になったのか¶

Pythonのプロジェクト管理は、昔から少し複雑でした。特にライブラリを作って配布する場面では、どのツールを使ってビルドするのか、どの依存関係が必要なのかを明確に伝える必要があります。

そこで導入されたのがpyproject.tomlです。もともとはビルドに必要な情報をツールへ伝える目的が大きく、PEP 518という提案で導入されました。

現在はそれだけではありません。パッケージ管理、コード整形、静的解析、テストなど、開発設定の集約にも使われます。

初心者の方は、ここで難しく考えなくて大丈夫です。まずは、Pythonプロジェクトの設定が集まる場所と覚えておけば十分です。

TOMLとはどんな形式か¶

pyproject.tomlの.tomlは、TOMLという設定ファイル形式を意味します。TOMLは、人間が読み書きしやすいことを意識して作られた形式です。

たとえば、次のように書きます。

[project]
name = "sample-app"
version = "0.1.0"
description = "A sample Python project"
requires-python = ">=3.11"

[project]のように角括弧で囲まれた部分は、設定のグループです。その下にname = "sample-app"のような形で、項目名と値を書いていきます。

JSONやYAMLを見たことがある人なら、設定ファイルの仲間だと考えると理解しやすいです。

pyproject.tomlの基本構造¶

ここからは、よく出てくる構造を見ていきます。

まず重要なのは、pyproject.tomlにはいくつかの代表的なセクションがあるということです。

この3つを理解できれば、pyproject.tomlの大枠はつかめます。特に初心者がよく見るのは[project]と[tool.xxx]です。

build-systemの役割¶

[build-system]は、プロジェクトをビルドするときに必要な情報を書く場所です。

たとえば、setuptoolsを使う場合は次のように書きます。

[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.build_meta"

初心者のうちは、ここを深く理解しなくても問題ありません。ライブラリを公開したい、社内で配りたい、という段階で重要になります。

projectの役割¶

[project]は、プロジェクトの基本情報を書く場所です。

例を見てみましょう。

[project]
name = "weather-cli"
version = "0.1.0"
description = "天気情報を取得するCLIツール"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.32",
    "python-dotenv>=1.0"
]

この例では、Python 3.11以上が必要で、requestsとpython-dotenvに依存していることがわかります。

こうして書いておくと、別の人がプロジェクトを見たときに必要な情報をすぐ確認できます。

toolセクションの役割¶

[tool.xxx]は、各ツールの設定を書く場所です。たとえばRuffの設定なら[tool.ruff]、pytestの設定なら[tool.pytest.ini_options]のように書きます。

次の例では、Ruffとpytestの設定をまとめています。

[tool.ruff]
line-length = 88
target-version = "py311"

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]

別ファイルに分かれていた設定を、pyproject.tomlにまとめられるのが便利な点です。

requirements.txtとの違い¶

Python初心者が混乱しやすいのが、requirements.txtとの違いです。

ただし、役割は少し違います。requirements.txtは、基本的にはインストールするライブラリ一覧を書くファイルです。

一方でpyproject.tomlは、プロジェクト情報やツール設定まで含められます。より広い範囲を管理するファイルです。

では、requirements.txtはもう不要なのでしょうか。答えは、プロジェクトによります。

アプリ開発では、環境固定のためにrequirements.txtやロックファイルを使うことがあります。一方で、ライブラリ開発ではdependenciesに必要な範囲を書くケースが増えています。

私の実感としては、初心者の学習段階ではrequirements.txtから入っても大丈夫です。ただ、チーム開発や実務コードに触れるなら、早めにpyproject.tomlの読み方を覚えておくと安心です。

【関連記事】Pythonの仮想環境とは？venvの作り方と使い分け

最小構成のpyproject.tomlを書いてみよう¶

ここからは、初心者向けに最小構成の例を作ってみます。

プロジェクト構成は次のようにします。

sample_project/
├── pyproject.toml
├── src/
│   └── sample_app/
│       └── __init__.py
└── tests/
    └── test_sample.py

pyproject.tomlは次のように書けます。

[build-system]
requires = ["setuptools>=68", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "sample-app"
version = "0.1.0"
description = "初心者向けのサンプルPythonアプリ"
requires-python = ">=3.11"
dependencies = [
    "requests>=2.32"
]

[tool.pytest.ini_options]
testpaths = ["tests"]

この時点で、プロジェクト名、バージョン、必要なPythonバージョン、依存ライブラリ、テスト対象フォルダが1つのファイルにまとまりました。

最初はコピペでも大丈夫です。大事なのは、何がどこに書かれているかを少しずつ読めるようになることです。

よく使うツール設定の例¶

pyproject.tomlの便利さは、ツール設定をまとめられるところにあります。

ここでは、初心者でも見かける機会が増えている設定例を紹介します。

Ruffの設定例¶

Ruffは、Pythonコードのチェックや整形に使われる高速なツールです。近年のPython開発では採用されることが増えています。

[tool.ruff]
line-length = 88
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I"]

line-lengthは1行の長さの目安です。

細かいルールを全部覚える必要はありません。まずは、コードの書き方を自動でチェックする設定だと理解すれば十分です。

Blackの設定例¶

Blackは、Pythonコードを自動で整形するツールです。チーム開発では、誰が書いても似た見た目のコードにそろえられるのが大きなメリットです。

[tool.black]
line-length = 88
target-version = ["py311"]

コードの見た目で迷う時間は、意外と大きなコストです。整形ツールを入れるだけで、レビューの会話がかなり本質的になります。

pytestの設定例¶

pytestは、Pythonでテストを書くときによく使われるツールです。テスト対象のフォルダやファイル名のルールをpyproject.tomlに書けます。

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py", "*_test.py"]

【関連記事】pytest入門｜Pythonでテストを書く基本を初心者向けに解説

実務でよくあるpyproject.tomlの使い方¶

実務では、pyproject.tomlは開発方針を共有する土台になります。

チーム開発では、全員が同じPythonバージョン、整形ルール、テスト設定を使う必要があります。人によってバラバラだと、動く人と動かない人が出てしまいます。

そこでpyproject.tomlにルールをまとめます。すると、新しく参加した人もまずこのファイルを見れば、開発環境の前提をつかみやすくなります。

現場で特に助かるのは、レビュー時の認識合わせです。設定として残っていれば、口頭説明や個人メモに頼らなくて済みます。

初心者がつまずきやすいポイント¶

便利なpyproject.tomlですが、初心者がつまずきやすいところもあります。ここでは、最初に知っておくと安心なポイントを整理します。

まず多いのが、インデントやカンマのミスです。TOMLは比較的読みやすい形式ですが、配列の書き方や文字列のクォートを間違えるとエラーになります。

次に、どのツールがどの設定を読むのかがわからなくなる問題があります。[tool.ruff]はRuff用、[tool.black]はBlack用、[tool.pytest.ini_options]はpytest用というように、セクション名とツール名を対応させて見るのがコツです。

さらに、dependenciesと開発用ライブラリの分け方も迷いやすいです。アプリの実行に必要なものと、テストや整形だけに必要なものは分けて管理されることがあります。

たとえば、ライブラリ本体に必要なものはdependenciesに書き、開発時だけ使うものはツールやパッケージ管理ツール側の仕組みで分けるケースがあります。Poetryやuvなどを使う場合は、それぞれ独自の書き方も出てきます。

Poetryやuvとの関係¶

Pythonのプロジェクト管理ツールとして、Poetryやuvという名前を聞くことがあります。これらのツールもpyproject.tomlを活用します。

基本の考え方は、pyproject.tomlにプロジェクトの希望や設定を書き、ロックファイルに実際のバージョンを記録するというものです。まずはpyproject.tomlが中心にある、と覚えておきましょう。

【関連記事】pipとは？Pythonライブラリのインストール方法を初心者向けに解説

pyproject.tomlを学ぶメリット¶

pyproject.tomlを学ぶメリットは、Pythonプロジェクト全体の構造を理解しやすくなることです。

初心者のうちは、コードを書くことに意識が向きます。それは当然ですし、とても大切です。

ただ、実務ではどう動かすか、どうテストするか、どう品質を保つかも重要です。pyproject.tomlは、その周辺知識への入口になります。

特に次のような場面で役立ちます。

• GitHubで公開されているPythonプロジェクトを読むとき
• チーム開発に参加して環境構築をするとき
• 自作ライブラリを作って配布したいとき
• Ruffやpytestなどの設定を確認したいとき

こうした場面でpyproject.tomlが読めると、プロジェクトの全体像をつかむスピードが上がります。これは、初心者から一歩進むための大きな武器です。

まず何から覚えればいいか¶

ここまで読んで、少し情報が多いと感じた方もいるかもしれません。大丈夫です。

最初に覚えるべきことは多くありません。まずは次の3つだけで十分です。

慣れてきたら、Ruff、pytest、Black、mypyなど、自分が使うツールの設定を少しずつ読んでいきましょう。読むだけでも十分な学習になります。

まとめ¶

pyproject.tomlは、Pythonプロジェクトの設定をまとめる重要なファイルです。プロジェクトの説明書だと考えると理解しやすくなります。

特に、プロジェクト情報、依存ライブラリ、ビルド設定、ツール設定を1つの場所で確認できる点が大きなメリットです。設定が見えると、Python開発の全体像も見えやすくなります。

私の経験から言うと、pyproject.tomlを読める人は、プロジェクト参加時の立ち上がりが早いです。

Pythonを学び始めたばかりの方は、まず既存プロジェクトのpyproject.tomlを開いてみてください。最初はname、requires-python、dependencies、[tool.xxx]を探すだけで十分です。

少しずつ読めるようになると、Pythonプロジェクトの見え方が変わります。pyproject.tomlは、初心者から実務レベルへ進むための小さくて大きな一歩です。

ここまでお読みいただきありがとうございました！