Pythonの設定ファイル設計ガイド｜YAML/TOML/ENVの使い分けと安全な管理術

はじめに

Pythonで開発を続けていると、必ずと言っていいほど悩むのが設定ファイルの管理です。
データベースの接続情報、APIキー、ログレベル、実行モード──
最初は数行だった設定が、気づけばコードやファイルに散らばり、

「どこを直せばいいのかわからない」
「本番と開発環境の切り替えが怖い」

そんな状態になっていませんか？

私自身、Python初心者の頃は設定値をそのままコードに書いてしまい、
あとから 環境切り替え・デプロイ・セキュリティ対応 で何度も痛い目を見ました😅
設定ファイルの設計は後回しにされがちですが、
実はここを雑にすると、プロジェクトは驚くほど早く壊れます。

逆に言えば、
YAML・TOML・JSON・環境変数（.env）を正しく使い分けるだけで、

• 環境差分に強くなる
• 秘密情報を安全に管理できる
• 設定変更が怖くなくなる

といった「長く育てられるPythonプロジェクト」に変わります。

この記事では、Pythonの設定ファイル設計ガイドとして、

• YAML / TOML / ENV は何が違い、どう使い分けるべきか
• 環境変数と .env を安全に扱う実践ルール
• Pydanticを使った型安全な設定管理のメリット
• 小規模プロジェクトでも破綻しない現実的な構成例

を、実務目線でわかりやすく解説します。

「設定が増えてきて、そろそろちゃんと整理したい」
そんなタイミングの方に向けた、失敗しにくい実践ガイドです。
それでは一緒に、Pythonの設定設計を整理していきましょう ✨

---

1. なぜ「設定ファイル設計」がPythonプロジェクトの寿命を左右するのか

Pythonは手軽に書けて、すぐ動くのが魅力ですよね。
その反面、プロジェクト初期は設計を深く考えなくても進めてしまえるという側面もあります。

特に多いのが、こんな状態です。

• 定数や設定値をそのままコードに書いている
• 環境ごとの差分を if 文で分岐している
• APIキーやURLが複数ファイルに散らばっている

最初は問題なくても、機能が増えたり、人が増えたり、環境が分かれたりすると、 この「設定の置き場が曖昧な状態」が一気に足を引っ張ります。

ハードコードが招く3つの問題

設定をハードコードすると、主に次のような問題が起きやすくなります。

• 可読性が下がる
  ロジックの中に設定値が混ざり、コードを読んだときに意図がつかみにくくなります。
• 変更コストが高くなる
  設定を変えるだけなのに、コード修正・テスト・再デプロイが必要になります。
• 事故が起きやすくなる
  本番用の設定をうっかり開発環境に使ってしまう、という典型的なミスが発生します。

こうした問題は、スキル不足というよりも、 「設定は後で考えればいい」という判断の積み重ねで起こることがほとんどです。

設定は「コードの外側」にある仕様

大事なのは、設定を「ただの値」ではなく、 アプリケーションの仕様の一部として扱うことです。

どんな環境で動くのか、何を切り替えられるのか、どこが変更可能なのか。
それらをコードから切り離して明確にすることで、 プロジェクトは壊れにくく、育てやすくなります。

---

2. Pythonプロジェクトにおける設定管理の全体像（設計思想）

設定ファイル設計でつまずきやすい理由のひとつが、
「何をどこまで設定として扱うのか」が曖昧なまま進んでしまうことです。

まず大前提として押さえておきたいのは、
設定には役割の違うものが混ざりやすいという点です。

設定は大きく3種類に分けて考える

• アプリケーション設定
  ログレベル、タイムアウト値、機能フラグなど、動作を調整するための値
• 環境依存の設定
  DBの接続先、外部APIのURL、実行モード（dev / prod など）
• シークレット情報
  パスワード、APIキー、トークンなどの機密情報

これらをすべて「設定ファイル」という一言でまとめてしまうと、
管理もセキュリティも一気に難しくなります。

Clean Architecture的に見る「設定」の立ち位置

設定をどう扱うかを考えるとき、
Clean Architectureの考え方はとても参考になります。

ポイントはシンプルで、
ビジネスロジックは設定の存在をできるだけ知らない、という発想です。

たとえば、core層のコードが os.environ を直接読んだり、 設定ファイルのパスを意識したりするのは、あまり美しい形ではありません。

設定の読み込みや解決は、
infra層やエントリポイント側で完結させ、
coreには「すでに解決された値」だけを渡す。

こうすることで、設定変更の影響範囲を最小限に抑えられ、
テストもしやすくなります。

「なぜここに設定があるのか」を説明できるか

設定設計で大切なのは、
今の配置にちゃんと理由があるかです。

「なんとなくここに置いた」設定は、
後から必ず混乱を生みます。

もし、 設定の責務分離って難しい… と感じたら、設計の考え方そのものを整理するのもおすすめです。

Clean Architecture 達人に学ぶソフトウェアの構造と設計 は、
設定だけでなく、 「依存方向をどう守るか」「責務をどう分けるか」を 腹落ちさせてくれる一冊です。

Clean Architecture 達人に学ぶソフトウェアの構造と設計
✅ Amazonでチェックする ｜✅ 楽天でチェックする

---

3. 推奨プロジェクト構成と設定ファイルの置き場所

設定の考え方が整理できたら、次は「どこに置くか」です。
置き場所が曖昧だと、どんなに良い設計でも運用で崩れてしまいます。

ここでは、現代的なPythonプロジェクトでよく採用されている構成をベースに、 設定ファイルの置き場所を見ていきましょう。

srcレイアウトを前提に考える

最近のPythonプロジェクトでは、
実行コードを src/ ディレクトリ配下にまとめる srcレイアウト がよく使われます。

my_project/
├─ pyproject.toml
├─ src/
│  └─ my_project/
│     ├─ core/
│     ├─ infra/
│     └─ cli.py
├─ config/
│  ├─ config.yaml
│  └─ config.dev.yaml
└─ tests/

この構成の良いところは、
実行コードと設定・テストの責務が自然に分かれる点です。

設定ファイルはコードの「外」に置く

設定ファイルは、
src/ の中には置かず、 プロジェクト直下や config/ ディレクトリにまとめるのが一般的です。

こうしておくと、

• パッケージとして配布するコードに設定が混ざらない
• 環境ごとの設定差分を管理しやすい
• 設定変更がコード変更と混同されにくい

といったメリットがあります。

pyproject.tomlに書くもの・書かないもの

pyproject.toml はとても便利ですが、 何でも書いていいわけではありません。

基本的な役割は次の通りです。

• 依存関係の管理
• ビルド設定
• ツール設定（pytest / ruff / mypy など）

一方で、次のようなものは書かないほうが無難です。

• 環境ごとに変わる値
• 実行時に切り替えたい設定
• 機密情報

pyproject.toml は 「プロジェクトの設計図」、 アプリケーション設定は 「運用のための情報」 と考えると、線引きしやすくなります。

環境別設定ファイルの分け方

実務では、環境ごとに設定を分けるケースがほとんどです。

config/
├─ config.yaml        # 共通設定
├─ config.dev.yaml    # 開発環境
├─ config.stg.yaml    # ステージング
└─ config.prod.yaml   # 本番環境

実行時に環境変数で読み込む設定ファイルを切り替えることで、 同じコードを使い回せるようになります。

---

4. 設定ファイル形式の選び方【INI / JSON / YAML / TOML】

設定ファイルを設計するときに、必ず出てくるのが
「結局、どの形式を使えばいいの？」という疑問です。

結論から言うと、
万能な形式は存在しません。
大切なのは「用途」と「運用する人」に合っているかどうかです。

まずは判断軸をはっきりさせる

形式を選ぶ前に、次のポイントを考えてみてください。

• 人が直接編集する機会は多いか？
• コメントを書きたいか？
• 階層構造やリストを扱う必要があるか？
• Python標準ライブラリで完結させたいか？

これだけでも、候補はかなり絞れます。

INI：とにかくシンプルに始めたいとき

INI形式は、とてもシンプルで読み書きしやすいのが特徴です。
Python標準ライブラリの configparser で扱えるのも大きな利点ですね。

ただし、階層構造やリスト表現が苦手なので、
設定が増えてきたプロジェクトでは窮屈に感じることもあります。

JSON：機械向け・汎用性重視

JSONは多くの言語で使われており、
データ構造をそのまま表現できるのが強みです。

一方でコメントが書けないため、
人が直接編集・レビューする設定ファイルとしては不便に感じやすいです。

YAML：人が読む設定ファイルなら有力候補

YAMLはインデントによる階層表現で、
見た目がスッキリしていて可読性が高いのが魅力です。

設定ファイルを人が触る前提なら、
YAMLを選ぶケースはとても多いです。

ただし、インデントミスによる事故や、
Pythonでは yaml.safe_load() を使う必要がある点には注意しましょう。

TOML：設定ファイル専用としてバランスが良い

TOMLは「設定ファイルのための形式」として設計されています。
INIに近い書き心地で、型が明示的なのが特徴です。

Python 3.11以降では tomllib が標準ライブラリに含まれているため、
外部依存を増やしたくない場合にも向いています。

迷ったときのざっくり指針

• 小規模・超シンプル → INI
• 機械連携・汎用データ → JSON
• 人が読む・編集する → YAML
• 設定専用・長期運用 → TOML

形式選びで悩みすぎるより、
「決めて、運用し、必要なら変える」くらいの感覚がちょうどいいです。

---

5. 環境変数と .env をどう使い分けるか

設定ファイルの形式を決めたあとに、必ず向き合うのが
「環境変数をどう扱うか」という問題です。

特に、パスワードやAPIキーなどの機密情報は、
設定ファイルに直接書かず、環境変数で管理するのが基本です。

なぜ機密情報は環境変数に分離するのか

機密情報を設定ファイルに書いてしまうと、

• 誤ってGitにコミットしてしまう
• レビューや共有時に漏れる
• 環境ごとの差分管理が難しくなる

といったリスクが一気に高まります。

環境変数であれば、
コードや設定ファイルとは物理的に分離できるため、 セキュリティ面で大きなメリットがあります。

.env ファイルは「開発用の補助」と考える

ローカル開発では、毎回環境変数を手動で設定するのは大変です。
そこで登場するのが .env ファイルです。

.env はあくまで 環境変数をまとめて定義するための補助ファイルです。

重要なポイントは次の2つです。

• .env はGitにコミットしない
• 本番環境では直接環境変数を設定する

このルールを守るだけでも、事故の確率はかなり下がります。

dotenvを使った基本的な流れ

Pythonでは、python-dotenv を使うことで、 .env ファイルを簡単に読み込めます。

from dotenv import load_dotenv
import os

load_dotenv()

db_user = os.environ["DB_USER"]
db_pass = os.environ["DB_PASS"]

ただし、このように os.environ を直接あちこちで参照し始めると、 また別の混乱を招きます。

---

6. Pydantic（pydantic-settings）による型安全な設定管理

環境変数や設定ファイルを使い始めると、次に直面しやすいのが
「値の型や存在をどう保証するか」という問題です。

たとえば、 数値のはずが文字列だった、 必須の環境変数が設定されていなかった、 こうしたミスは実行時まで気づきにくく、原因調査も大変です。

なぜ「設定にも型」が必要なのか

設定に型を持たせることで、次のようなメリットがあります。

• アプリ起動時に設定ミスを即座に検知できる
• どんな設定が必要なのかがコードから分かる
• IDEの補完が効き、扱いやすくなる

これをシンプルに実現できるのが、
pydantic-settings（旧 BaseSettings）です。

Settingsクラスで設定を一元管理する

考え方はとてもシンプルで、
「設定を表すクラス」を1つ用意するだけです。

from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    app_name: str
    debug: bool = False
    timeout: int = 30

    class Config:
        env_prefix = "MY_APP_"

settings = Settings()

この例では、
MY_APP_APP_NAME や MY_APP_DEBUG といった環境変数が 自動的に読み込まれます。

型が合わない、必須項目が足りない、といった場合は、
起動時にエラーとして検出されるため、 本番事故を未然に防ぎやすくなります。

設定は「入口」でまとめて解決する

Pydanticを使うときのコツは、
設定の読み込みをエントリポイントで完結させることです。

core層や業務ロジックでは、 settings.timeout のように 解決済みの値だけを受け取る形にします。

こうすることで、

• テストが簡単になる
• 設定変更の影響範囲が限定される
• 設計がブレにくくなる

Pythonicな設計を身につけたい人へ

設定管理を含めて、 「Pythonらしい設計とは何か？」を体系的に学びたい場合は、 Effective Python 第3版 がとても参考になります。

Effective Python 第3版
✅ Amazonでチェックする ｜✅ 楽天でチェックする

---

7. レガシー環境・既存コードで役立つ実践テクニック

理想的な設定設計が分かっていても、
現実には「すでに動いているコード」をいきなり作り直すのは難しいですよね。

ここでは、レガシーなPythonプロジェクトや、 既存コードを壊さずに少しずつ改善していくための考え方を紹介します。

一気に直そうとしない

設定まわりの改善でよくある失敗が、
最初から完璧を目指してしまうことです。

大規模なリファクタリングは、
バグの温床になりやすく、心理的なハードルも高くなります。

まずは次のような小さな一歩がおすすめです。

• ハードコードされた値を1か所に集める
• 設定ファイルを新規作成し、参照を切り替える
• 環境変数に移せるものから移す

既存の設定形式を尊重する

すでにINIやYAMLが使われているなら、
無理に別形式へ移行する必要はありません。

大切なのは形式よりも、
「設定の責務が整理されているか」です。

既存の設定を読み込んだあと、
PydanticのSettingsクラスに流し込むだけでも、 安全性と見通しは大きく改善します。

レイヤード構成で段階的に上書きする

実務では、設定を1ファイルですべて管理しようとすると破綻しがちです。

そこで有効なのが、
レイヤード構成という考え方です。

default設定
  ↓
環境別設定（dev / prod）
  ↓
ローカル設定（.envなど）

後から読み込まれた設定で上書きするだけでも、
環境差分の管理がかなり楽になります。

「今あるコードを良くする」視点を持つ

レガシー改善では、 「正解に近づく」よりも 「昨日よりマシにする」くらいの感覚が大切です。

既存コードを読み解きながら設計を改善していく力は、 実務でとても役立ちます。

そうした視点を鍛えるのに向いているのが、 Effective Python 第2版です。 既存コードをどう読み、どう改善するかという観点で、 今でも十分に学びがあります。

Effective Python 第2版
✅ Amazonでチェックする ｜✅ 楽天でチェックする

---

8. セキュリティと運用で絶対に外せないポイント

設定ファイル設計は、
きれいに整理できた時点で終わり…ではありません。

実際の現場では、「どう安全に運用し続けるか」が 一番の課題になります。

パスワードは「暗号化」ではなく「ハッシュ」

よくある誤解ですが、
パスワードを保存する場合は復号できない形で扱うのが基本です。

bcrypt や scrypt は「暗号化」ではなく、 ハッシュ化のための仕組みです。

設定ファイルに平文のパスワードを書くのではなく、

• アプリ側ではハッシュ値のみを扱う
• 認証時に入力値を同じ方法でハッシュして比較する

という設計にしておくと、万一の漏洩時も被害を最小限に抑えられます。

設定ファイルのアクセス権限を見直す

ファイルの中身だけでなく、
「誰がその設定を読めるのか」も重要です。

Linux環境であれば、

chmod 640 config.yaml

のように、実行ユーザー以外が読めないように制限するだけでも、 セキュリティレベルは大きく変わります。

シークレット管理ツールを使う判断基準

プロジェクトが成長してくると、 環境変数や .env だけでは管理しきれなくなります。

次のような状況になったら、 シークレット管理ツールの導入を検討しましょう。

• 本番環境が複数ある
• 鍵のローテーションが必要
• 誰がいつアクセスしたかを追跡したい

AWS Secrets Manager や HashiCorp Vault などを使うことで、 保管・アクセス制御・監査をまとめて管理できます。

起動時に「設定が正しいか」を必ず確認する

設定ミスは、
実行してから気づくほどダメージが大きくなります。

Pydanticを使っていれば、 起動時に設定を読み込んだ時点で 不正な値をエラーとして止めることができます。

---

まとめ

Pythonの設定ファイル設計は、
「後で何とかしよう」と思っているうちに、 いつの間にかプロジェクト全体を縛る存在になりがちです。

この記事では、

• なぜ設定設計が重要なのか
• 設定の責務をどう分けるべきか
• 形式（INI / JSON / YAML / TOML）の選び方
• 環境変数・.env・Pydanticの役割
• レガシー環境での現実的な改善方法
• セキュリティと運用で気をつけるポイント

を、実務目線で整理してきました。

私自身の経験から言うと、
設定ファイル設計で一番大事なのは 「完璧を目指さないこと」だと思っています。

形式選びに悩みすぎたり、 最新ツールを全部取り入れようとしたりするよりも、
今の規模に合った整理を一歩ずつ進めるほうが、 結果的に長く使える構成になります。

設定が整理されると、 コードは驚くほど読みやすくなり、 「触るのが怖いプロジェクト」から 「安心して育てられるプロジェクト」に変わっていきます。

もし今、 設定が増えてきて不安になってきた と感じているなら、
それは見直しのベストタイミングです。

この記事が、 あなたのPythonプロジェクトを 少しでも扱いやすくするきっかけになれば嬉しいです✨

あわせて読みたい

• Pythonでiniファイルを使う方法｜configparserの基本と読み書きの実例付き！
• 【Python入門】YAMLファイルの書き方と使い方｜設定ファイルの操作をわかりやすく解説！
• Pydanticとは？Pythonで安全なデータバリデーションを簡単に実装する方法

---

参考文献

• Working with Python Configuration Files: Tutorial & Best Practices
• Python Efficient Configuration Management
• What’s the best practice using a settings/config file in Python?（Stack Overflow）
• Pythonにおける設定ファイル管理の考え方（Qiita）
• Python公式ドキュメント：configparser
• Simplify Your Python Project’s Configuration
• Python YAML Configuration with Environment Variables Parsing
• TOML（Wikipedia）
• Pythonで環境変数を扱う方法まとめ（Qiita）
• Use Cases for Python Environment Variables

よくある質問（Q&A）