はじめに
Pythonでプロジェクトを作り始めたとき、
「とりあえず動けばいいか」とファイルを置いていった結果、
あとからディレクトリ構成がぐちゃぐちゃになって困った経験はありませんか？
Pythonは自由度が高く、個人開発から業務システムまで幅広く使える言語です。
一方で、「Pythonプロジェクトのディレクトリ構成」には明確な正解が見えにくく、
初心者ほど迷いやすいポイントでもあります。
最初は1ファイルの小さなスクリプトだったのに、
機能が増え、テストを書き、パッケージ化や配布を意識し始めた瞬間に、
・どこにファイルを置けばいいかわからない
・importが増えて読みづらくなる
・テストコードが書きにくい
といった壁にぶつかる人はとても多いです。
実はこれ、コードの書き方そのものではなく、
プロジェクトのディレクトリ構成設計が原因で起きているケースがほとんどです。
この記事では、Python初心者の方でもそのまま真似できるように、
・なぜPythonではディレクトリ構成が重要なのか
・よくある構成パターンと失敗しやすいポイント
・現代のPython開発で「王道」とされる src レイアウト
・小さなプロジェクトを無理なく育てていく設計の考え方
を、理由 → 具体例 → 実践イメージの順で整理して解説します。
「今は個人開発だけど、将来は規模が大きくなるかもしれない」
「仕事でも通用するPythonプロジェクト構成を身につけたい」
そんな方が、迷わず使えるディレクトリ設計の土台を持ち帰れる内容を目指しました。
難しい設計理論よりも、
まずは「なぜその構成にするのか」が腹落ちすることを大切に進めていきます。
それでは、なぜPythonプロジェクトはディレクトリ構成で失敗しやすいのか、
順番に見ていきましょう。
1. なぜPythonプロジェクトはディレクトリ構成で失敗しやすいのか
Pythonはとても柔軟な言語です。
ファイルの置き場所についても強い制約がなく、極端に言えば どこに書いても動いてしまうことが多いですよね。
でも、この「自由さ」こそが、あとで困る原因になりやすいポイントなんです。
開発環境では動くのに、本番や配布で壊れる
よくあるのが、次のようなケースです。
- ローカル実行では問題ない
- テストも通っている
- なのに、別環境で動かすと
ImportErrorが出る
これはPythonがカレントディレクトリを優先して import を解決する 仕組みを持っているためです。
ディレクトリ構成が曖昧だと、 「本来はパッケージとして扱うべきコード」を たまたま同じ場所にあるから import できている 状態になりがちなんですね。
プロジェクトが育つほど、構成の歪みが表に出る
作り始めたばかりの頃は、ファイルが数個しかありません。
その段階では、多少雑でも大きな問題は起きません。
ただ、次のようなタイミングで一気に苦しくなります。
- 機能が増えてファイル数が増えたとき
- テストを書き始めたとき
- 他の人にコードを渡すとき
- pipで配布・インストールしようとしたとき
この段階でディレクトリ構成が整理されていないと、
- どこに何があるのかわからない
- 依存関係が追えない
- ちょっと触っただけで別の場所が壊れる
いわゆるスパゲッティコードや、 分割しすぎて全体像が見えないラビオリコードに 近づいていきます。
テストと本番コードが混ざると、安心できなくなる
もうひとつ多いのが、 テストコードと本番コードが同じ場所にある構成です。
この状態だと、
- テスト用の便利関数を本番から誤って使ってしまう
- 「テストでは通るけど実運用では怪しい」状態になる
という問題が起きやすくなります。
テストはできるだけクリーンな環境で実行されるべきなので、 ディレクトリレベルで分離しておくことがとても重要です。
ここまで見ると、 ディレクトリ構成は単なる見た目の問題ではなく、 Pythonプロジェクトの安全装置のような役割を 持っていることがわかります。
次の章では、実際によく使われる 代表的なディレクトリ構成パターンと、 それぞれのメリット・限界を整理していきます。
2. 代表的なディレクトリ構成パターンとその限界
Pythonプロジェクトのディレクトリ構成には、 いくつかよく使われる定番パターンがあります。
どれも一度は通る道ですが、 それぞれに向き・不向きがあるのが正直なところです。
ここでは初心者がつまずきやすいポイントに注目しながら、 代表的な3つの構成を見ていきましょう。
フラット構成（すべてをルートに置く）
もっともシンプルなのが、すべてのPythonファイルを プロジェクト直下に置くフラット構成です。
project/
├── main.py
├── utils.py
├── config.py
└── test_main.py
小さなスクリプトや検証用コードでは、 この形でも十分に機能します。
ただし、ファイルが増え始めると、
- ファイル名の衝突が起きやすい
- 役割の違いが見えにくい
- import関係が曖昧になる
といった問題が一気に表面化します。
「とりあえず動かす」段階を超えたら、 長く使い続けるのは少し厳しい構成です。
パッケージ直下構成（プロジェクト名＝パッケージ）
次によく見かけるのが、 プロジェクト名と同じフォルダを作り、 その中にコードをまとめる構成です。
project/
├── my_package/
│ ├── __init__.py
│ ├── main.py
│ └── utils.py
├── tests/
└── setup.py
パッケージとしての形がはっきりしており、 フラット構成よりは整理されています。
ただし、この構成には初心者が気づきにくい落とし穴があります。
- インストールしていなくても import が通ってしまう
- 「本当に配布可能な状態か」をテストで検証しにくい
カレントディレクトリにパッケージが存在するため、 実際の配布環境とは違う条件で動いてしまうんですね。
srcレイアウト（現代的で推奨される構成）
そこで登場するのが、srcレイアウトです。
project/
├── pyproject.toml
├── src/
│ └── my_package/
│ ├── __init__.py
│ ├── main.py
│ └── utils.py
├── tests/
ソースコードを src/ 配下に置くことで、 インストールされていないパッケージは import できない 状態を作れます。
これにより、
- 配布後と同じ条件で動作確認できる
- テストの信頼性が高まる
- importミスに早く気づける
といったメリットがあります。
最初は少しだけ構成が複雑に見えますが、 プロジェクトが成長するほど 「最初に選んでおいてよかった」 と感じる構成です。
次の章では、この src レイアウトをベースにした 初心者がそのまま使える標準構成例 を、具体的に見ていきます。
3. 結論：初心者が採用すべき「srcレイアウト」の標準構成
ここまで見てきた通り、
Pythonプロジェクトを長く・安全に育てていくためには、 srcレイアウトを前提にした構成がもっとも安定しています。
この章では、初心者でもそのまま使える 標準的なディレクトリ構成例を整理します。
推奨される基本構成
project-name/
├── pyproject.toml # プロジェクト設定・依存関係管理
├── README.md # プロジェクト概要・使い方
├── LICENSE # ライセンス情報
├── .gitignore # Git管理対象外の指定
├── src/ # ソースコード本体
│ └── your_package/ # パッケージ名
│ ├── __init__.py # パッケージ初期化
│ ├── main.py # エントリーポイント
│ ├── core/ # ドメインロジック
│ └── infra/ # 外部I/O（DB・APIなど）
├── tests/ # ユニットテスト
├── docs/ # ドキュメント
└── examples/ # 使用例サンプル
なぜこの構成が「迷わない」のか
この構成のポイントは、 役割ごとに置き場所が明確なことです。
- 本番コードはすべて
src/の中 - テストコードは
tests/に完全分離 - 設定・説明・補助ファイルはプロジェクト直下
「このファイル、どこに置けばいいんだっけ？」と 迷う場面がかなり減ります。
srcディレクトリがもたらす最大のメリット
srcレイアウトの一番の価値は、 パッケージとして正しく扱われているかを 強制できる点です。
開発中は、
- たまたま同じディレクトリにあるから import できる
- 本当は壊れているのに気づかない
という状態が起きがちです。
しかし src を挟むことで、 インストールされていないコードは使えない という健全な制約が生まれます。
これは、将来的に
- pipで配布する
- CIでテストを回す
- 別の人が環境を作る
といった場面で、確実に効いてきます。
最初は全部を使わなくていい
ここで紹介した構成は、 少し多く感じるかもしれません。
でも安心してください。
最初から core / infra / docs / examples を すべて使う必要はありません。
まずは、
src/your_package/tests/pyproject.toml
この3点セットだけでも十分です。
プロジェクトが成長したときに、 自然に拡張できる余白を残しておく。 それが、この標準構成の強さです。
次の章では、このディレクトリ構成を 「保守しやすいコード設計」へつなげる考え方 を見ていきます。
4. ディレクトリ設計を「保守しやすいコード」に育てる考え方
ディレクトリ構成を整えたからといって、
それだけでコードが読みやすく、壊れにくくなるわけではありません。
本当に大切なのは、その構成の上で、どんな考え方でコードを書くかです。
ここでは、srcレイアウトと相性がよく、 長く保守できるプロジェクトに育てやすい考え方を整理します。
「役割」で分けると、コードは自然に読みやすくなる
保守しやすいコードの共通点は、 ファイルやモジュールが何を担当しているのかが すぐに分かることです。
たとえば、
- 計算や判断などのロジック
- ファイル読み書きやAPI通信
- 設定値の読み込み
これらが1つのファイルに混ざっていると、 ちょっとした変更でも影響範囲が読みにくくなります。
srcレイアウトでは、
core/：ロジックの中心infra/：外部とのやり取り
のように、役割ごとに置き場所を決めやすいのが大きな利点です。
「変更されやすいもの」を奥に押し込む
プロジェクトが成長すると、 どうしても変更が多い部分と、ほとんど触らない部分が分かれてきます。
たとえば、
- API仕様の変更
- データ保存先の変更
- 設定項目の追加
こういった外部要因で変わりやすい処理を ロジックの中心に直接書いてしまうと、 修正のたびに全体を触ることになります。
だからこそ、
- core はできるだけ純粋に
- infra に外部依存を集める
という分離が効いてきます。
構成を作ったあとは「書き方」も大事
ディレクトリ構成はあくまで土台です。
その上で、Pythonらしい書き方や バグを生みにくい習慣を身につけると、 保守性は一段上がります。
そのときにとても参考になるのが、次の一冊です。
Effective Python 第3版
Pythonのベストプラクティスが具体例つきで整理されており、 「どう書けば後から困らないか」が自然と身につきます。
構成を整えたあとに読むと、 なぜその分け方が活きるのかが ぐっと理解しやすくなります。
Effective Python 第3版
✅ Amazonでチェックする｜ ✅ 楽天でチェックする
次の章では、ここで触れた core / infra 分離をもう一段深掘りして、 アーキテクチャ視点でのディレクトリ構成 を見ていきます。
5. core / infra 分離が活きるプロジェクト設計の考え方
ここまでで、core と infra を分ける構成が 保守性に効いてくる、という話をしてきました。
この章では、
- そもそも core / infra とは何か
- なぜ分けるとテストしやすくなるのか
を、できるだけ感覚的に整理していきます。
coreは「何をするか」を表す場所
core ディレクトリには、 アプリケーションの本質的な処理を置きます。
たとえば、
- 計算ルール
- 判定ロジック
- 業務上のルール
など、「外部環境が変わっても本来は変わらないもの」です。
ここでは、
- ファイルを直接読む
- データベースに接続する
- HTTPリクエストを投げる
といった処理は、できるだけ書かないようにします。
coreは純粋なPythonコードに近いほど、 テストしやすく、理解もしやすくなります。
infraは「どうやって実現するか」を担当する
一方で infra は、 coreで定義した処理を 現実世界とつなぐ役割を持ちます。
たとえば、
- データベースの実装
- 外部APIとの通信
- 設定ファイルや環境変数の読み込み
こうした処理は、環境や要件によって 変更されやすいのが特徴です。
だからこそ、 「変わりやすいもの」を infra にまとめておくと、 修正が局所的で済むようになります。
分離するとテストが一気に楽になる
core / infra を分ける最大のメリットのひとつが、 テストの書きやすさです。
coreが外部に依存していなければ、
- テスト用のデータをそのまま渡せる
- 環境構築なしでテストできる
- 結果が安定する
という状態を作れます。
「ロジックは正しいのか」 「外部との接続は正しいのか」
この2つを別々に検証できるようになるのが、 core / infra 分離の強さです。
小規模プロジェクトでも考え方だけは使える
ここまで読むと、 「ちょっと大げさでは？」と感じるかもしれません。
でも、最初から完璧に分ける必要はありません。
- これはロジックかな？
- これは外部依存かな？
と意識するだけでも、 ファイルの分け方はかなり変わります。
次の章では、この考え方をさらに一段広げて、 アーキテクチャ視点でディレクトリ構成を見る ところまで進めていきます。
6. レイヤード設計・アーキテクチャ視点で見るディレクトリ構成
core / infra を分ける考え方は、 実はもう一段大きな枠組みの一部です。
それが、アーキテクチャ設計という視点です。
ここでは難しい理論に踏み込まず、 「ディレクトリ構成とアーキテクチャはどうつながっているのか」 を感覚的に整理していきます。
ディレクトリ構成は「設計の結果」
よくある誤解として、
- 先にフォルダを作って
- あとから設計を考える
という順番があります。
でも実際は逆で、 設計の考え方が、そのままディレクトリ構成に表れる ことがほとんどです。
srcレイアウトで
- core
- infra
を分けているのも、 「依存の向きを整理したい」という設計意図があるからです。
レイヤード設計で見ると、構成の意味がはっきりする
レイヤード設計では、 システムを役割ごとの層（レイヤー）に分けて考えます。
たとえば、
- ドメイン（ルール・判断）
- アプリケーション（処理の流れ）
- インフラ（DB・API・外部サービス）
srcレイアウトの core / infra は、 この考え方を最低限の形で取り入れたもの と見ることができます。
つまり、 ディレクトリ構成を整えることは、 そのまま依存関係を整理することにつながるんですね。
将来スケールしても壊れにくい理由
アーキテクチャ視点で構成を考えておくと、 プロジェクトが成長したときに効いてきます。
- 機能追加でファイルが増えても迷わない
- 一部の差し替えで対応できる
- チーム開発でも役割分担しやすい
「今は小さいから不要」と思っていた考え方が、 後から大きな安心感になります。
設計の全体像をつかむなら、この一冊
ここまでの話を 「もう少し体系的に理解したい」と感じたら、 次の書籍がとても参考になります。
Architecture Patterns with Python
Pythonでのレイヤード設計や依存関係の考え方を、 実践ベースで解説している一冊です。
core / infra をなぜ分けるのか、
ディレクトリ構成と設計思想がどう結びつくのかが、 かなり腹落ちします。
Architecture Patterns with Python
✅ Amazonでチェックする｜ ✅ 楽天でチェックする
次の章では、 ここまでの考え方を踏まえて、 プロジェクト初期セットアップの具体的な手順 を順番に整理していきます。
7. プロジェクト初期セットアップの実践手順
ここまでで、 「なぜこのディレクトリ構成なのか」 「どんな考え方で分けているのか」 が見えてきたと思います。
この章では、実際に新しいPythonプロジェクトを立ち上げるときの 現実的な初期セットアップ手順を、 順番に整理します。
1. プロジェクトディレクトリとリポジトリを作成する
まずは、プロジェクト用のディレクトリを作成し、 Gitリポジトリとして初期化します。
mkdir project-name
cd project-name
git init
GitHubなどのリモートリポジトリを使う場合も、 基本的な流れは同じです。
2. src / tests ディレクトリを作成する
次に、最低限必要なディレクトリを用意します。
mkdir src tests
mkdir src/your_package
touch src/your_package/__init__.py
この段階では、 core や infra を無理に作らなくても問題ありません。
3. pyproject.toml を用意する
現代のPythonプロジェクトでは、 pyproject.toml が設定の中心になります。
Poetryなどのツールを使うと、 対話形式で基本設定を作成できます。
poetry init
ここで、
- プロジェクト名
- バージョン
- 対応Pythonバージョン
などを設定します。
4. 開発モードでインストールする
ディレクトリ構成ができたら、 プロジェクトを開発モードでインストールします。
poetry install
これにより、 from your_package import ... といった正しい import パスで 動作確認ができるようになります。
5. 品質管理ツールを導入する
最後に、コード品質を保つためのツールを設定します。
- Ruff（Lint / Formatter）
- Mypy（型チェック）
- pre-commit（コミット前チェック）
最初から完璧に設定しなくても大丈夫です。
「自動でチェックされる環境」を用意するだけでも、 バグの混入は大きく減ります。
まとめ
Pythonプロジェクトのディレクトリ構成は、
「見た目を整えるためのもの」ではありません。
それは、 コードを安全に育て続けるための土台です。
この記事では、
- なぜディレクトリ構成が重要なのか
- よくある構成パターンとその限界
- srcレイアウトを採用する理由
- core / infra 分離と設計の考え方
- 実践的な初期セットアップ手順
を順番に整理してきました。
最初は少し遠回りに感じるかもしれませんが、 早い段階で構成を整えておくと、 後からの修正コストが大きく下がります。
私自身も、 「動くからOK」で作ったプロジェクトを 何度も作り直してきました。
だからこそ、 迷いにくい標準構成を最初に持っておく ことの大切さを、強く感じています。
今回紹介した構成は、 そのままコピーして使っても問題ありませんし、 プロジェクトに合わせて少しずつ調整しても大丈夫です。
大切なのは、 「なぜこの構成なのか」を理解したうえで使うこと。
そうすれば、 プロジェクトが成長しても、 構成に振り回されることはなくなります 🙂
ぜひ、次に作るPythonプロジェクトから srcレイアウトを試してみてください。
あわせて読みたい
ディレクトリ構成を理解したあとに読むと、 実装や運用がぐっと楽になる関連記事をまとめました。
- 【Python入門】pathlibの使い方を完全解説｜フォルダー・パス操作が簡単になる方法
- Pythonでテストコードを書く方法｜初心者向けpytest入門ガイド
- Pythonでライブラリを一括インストールする方法｜requirements.txtの使い方
- 【リファクタリングとは？】初心者向けにコード改善の基本と具体例をやさしく解説！
参考文献・参考リンク
本記事の内容は、Pythonコミュニティで共有されている実践的な知見や、 公式・準公式ドキュメントを参考に整理しています。 さらに深く理解したい方は、以下の資料もあわせて参照してみてください。
- The Hitchhiker’s Guide to Python｜Project Structure（公式ガイド）
- Stack Overflow｜What is the best project structure for a Python application?
- Qiita｜Pythonプロジェクトのディレクトリ構成を考える
- Zenn｜Pythonパッケージ構成の考え方と実例
- Qiita｜Pythonプロジェクトの雛形と設計メモ
- GitHub｜python_package（実用的なパッケージ構成サンプル）
- Zenn｜個人開発向けPythonプロジェクトテンプレート
- rcmdnk.com｜Pythonプロジェクト構成と管理の考え方
- Zenn｜pyproject.tomlを中心としたPython開発環境構築
これらの資料は、
「なぜ src レイアウトが推奨されるのか」
「ディレクトリ構成と設計思想がどう結びつくのか」
を理解するうえで、非常に参考になります。
よくある質問（Q&A）
- Q小規模なスクリプトでも src レイアウトは必要ですか？
- A
単発のスクリプトであれば必須ではありません。
ただし「あとで機能を足すかも」「テストを書くかも」と感じたら、 最初から src レイアウトにしておく方が後悔しにくいです。構成を変えるコストは、後になるほど大きくなります。
- Q
__init__.pyは必ず置くべきですか？ - A
基本的には置くことをおすすめします。
特殊なケースとして namespace package もありますが、 初心者のうちは__init__.pyを置いた 「分かりやすいパッケージ構成」を前提にした方が安全です。
- QDjango や FastAPI でも同じ考え方でいいですか？
- A
フレームワーク固有の構成はありますが、
<ul> <li>役割で分ける</li> <li>外部依存を分離する</li> <li>テストと本番を分ける</li> </ul> <p> という考え方自体は共通です。今回の src / core / infra の発想を理解しておくと、 フレームワークの構成も読み解きやすくなります。
※当サイトはアフィリエイト広告を利用しています。リンクを経由して商品を購入された場合、当サイトに報酬が発生することがあります。
※本記事に記載しているAmazon商品情報（価格、在庫状況、割引、配送条件など）は、執筆時点のAmazon.co.jp上の情報に基づいています。
最新の価格・在庫・配送条件などの詳細は、Amazonの商品ページをご確認ください。