Python環境構築における .toml ファイル活用ガイド
1. はじめに
中級エンジニアとして、自身のプロジェクトで再現性・可搬性の高い環境構築を目指すには、従来の requirements.txt に加え、pyproject.toml を活用する方法が効果的です。
本ガイドでは、TOML形式の概要から、Poetryによる環境構築の詳細手順とディレクトリ構成、poetry new コマンドの内部動作、類似技術との比較までを解説します。
2. TOML とは
- TOML: "Tom's Obvious, Minimal Language" の略。
- 特徴: キー/値ペアによるシンプルな記述、セクションによる階層的構造、コメントサポート。
-
標準化: PEP 517/518/621 に準拠し、
pyproject.tomlが公式にビルド・依存管理設定ファイルとして採用。
# コメントは # で始める
[tool.example]
name = "sample_project"
version = "0.1.0"
3. TOML サンプル: pyproject.toml
[tool.poetry]
name = "awesome-app"
version = "0.1.0"
description = "中級者向けサンプルプロジェクト"
authors = ["aaa <aaaa@example.com>"]
[tool.poetry.dependencies]
python = "^3.10"
fastapi = "^0.95.0"
uvicorn = "^0.22.0"
[tool.poetry.dev-dependencies]
pytest = "^7.2"
[build-system]
requires = ["poetry-core>=1.0.0"]
build-backend = "poetry.core.masonry.api"
-
[tool.poetry]配下にメタ情報 -
dependencies/dev-dependenciesの分離により、本番と開発用依存を明確に管理
4. 環境構築のサンプルコードとディレクトリ構成
4.1 Poetry を使った例（詳細）
-
Poetry のインストール
curl -sSL https://install.python-poetry.org | python3 - export PATH="$HOME/.local/bin:$PATH" poetry --version # 確認 -
新規プロジェクトの作成
poetry new awesome-app cd awesome-app✅
poetry newで実行される内容poetry new プロジェクト名は、以下のような Python パッケージの雛形を自動生成します：awesome-app/ ├── pyproject.toml # 依存とビルド設定（TOML形式） ├── README.rst # プロジェクト説明用 ├── awesome_app/ # アプリケーション本体（パッケージ） │ ├── __init__.py │ └── main.py # 必要に応じて作成 └── tests/ # 単体テスト用ディレクトリ ├── __init__.py └── test_awesome_app.py -
依存ライブラリの追加
poetry add fastapi uvicorn poetry add --dev pytest-
dependencies: 本番環境や実行時に必要なパッケージ -
dev-dependencies: 開発・テスト・静的解析にのみ使うツール
-
-
仮想環境の作成・起動
poetry shell # 自動で仮想環境に入る（Poetry 2.0 ではプラグイン必要） poetry env info --path # 仮想環境のパス確認 source $(poetry env info --path)/bin/activate # 直接アクティブにする方法 -
アプリケーションの実行・開発フロー
-
開発サーバ起動：
uvicorn awesome_app.main:app --reload -
テスト実行：
pytest -
スクリプト定義（任意）：
[tool.poetry.scripts] start = "awesome_app.main:main"poetry run start
-
-
パッケージのビルドと公開
-
ビルド：
poetry build→
dist/以下に.whlと.tar.gzを生成 -
公開：
poetry publish --username __token__ --password <your_api_token>
PyPI への公開により、
pip install あなたのパッケージ名で他者に使ってもらえる状態になります。 -
5. 本番環境と開発環境の使い分け：dependencies と dev-dependencies
| セクション | いつ使う？ | 例 | インストール範囲 |
|---|---|---|---|
[tool.poetry.dependencies] |
本番・実行時に必要 | fastapi, requests, sqlalchemy |
poetry install --no-dev でもインストールされる |
[tool.poetry.dev-dependencies] |
開発・テスト専用 | pytest, black, mypy | 通常の poetry install 時のみインストールされる |
-
ローカルやCIでの開発時:
poetry install -
本番環境にデプロイ時（軽量化）:
poetry install --no-dev
このように、本番環境では不要なライブラリを省いて、軽量・安全な環境を構築できます。
6. poetry.lock とは何か？
poetry.lock は、Poetry が自動生成するロックファイルで、すべての依存ライブラリとそのバージョンを完全に固定するために使われます。
✅ 目的
- 同じ
pyproject.tomlでも、インストールするタイミングによって異なるバージョンの依存が入ることを防ぐ - すべての開発者／環境で同じ依存構成を再現する（再現性の確保）
✅ 内容例
[[package]]
name = "requests"
version = "2.31.0"
dependencies = [
"urllib3 >=1.26,<2.0",
"certifi >=2022.12.7"
]
✅ 開発フローでの使い方
- 初回
poetry addやpoetry installで自動生成される - チームやCI/CDでは、
poetry.lockを Git に含めて共有 - 本番環境でも同じ依存構成を再現可能
⚠️ 注意
- 手動で編集しない
- 必ずバージョン管理（Git）に含める
7. 類似技術との違い比較
| 技術 | 記述ファイル | 仮想環境管理 | ロック機能 | 備考 |
|---|---|---|---|---|
| requirements.txt | requirements.txt |
手動 (venv) |
× | シンプルだが再現性が限定的 |
| pip-tools |
requirements.in + requirements.txt
|
手動 (venv) |
○ | 依存解決とロックが可能 |
| Poetry |
pyproject.toml + poetry.lock
|
自動 | ○ | 一貫管理、公開機能も備える |
| PDM | pyproject.toml |
自動 | ○ | 軽量・PEP 準拠 |
| Conda | environment.yml |
自動 | ○ | 非Pythonパッケージも管理可能 |
| Hatch | pyproject.toml |
自動 | ○ | 柔軟な拡張性・プラグイン対応 |
| pipenv | Pipfile |
自動 | ○ | シンプルなユースケースに向く |
8. まとめ
-
.toml(TOML形式) は現代的なPythonプロジェクトの標準フォーマット。 -
pyproject.tomlを活用すると、依存・ビルド設定・ツール設定を一元管理できる。 - Poetry を中心に据えれば、中級者向けの再現性・可搬性の高い開発フローが実現可能。
-
poetry newによってプロジェクト雛形を素早く構築し、依存・仮想環境・テスト・ビルド・公開まで統合的に扱える点が強み。 -
dependenciesとdev-dependenciesの適切な使い分けにより、本番環境を安全かつ軽量に保つことができる。 -
poetry.lockにより、全ての環境で正確に同じ依存構成を再現可能にする。
プロジェクトの規模やチームの開発フローに応じて、.toml を中心とした構成を検討しましょう。