【Python】gitignore書き方入門｜これだけは除外すべきファイル一覧

Pythonで開発をしていると、気がつけば大量の不要ファイルがGitに含まれていて、履歴が見づらくなってしまうことがあります。

.gitignoreを正しく書いておくことで、こうした問題を未然に防ぎ、快適な開発環境を維持できます。

本記事では、Pythonプロジェクトで最低限入れておきたい.gitignoreの書き方と具体例を、テンプレート付きで丁寧に解説します。

Pythonの.gitignoreとは何か

.gitignoreの基本役割と仕組み

Gitでは、通常プロジェクトフォルダ内のすべてのファイルが管理対象の候補になります。

しかし、実際にはソースコードとは無関係なファイルや、自動生成されるファイルはバージョン管理から外した方が良いです。

このときに使うのが.gitignoreファイルです。

.gitignoreには「どのようなファイルやディレクトリをGitの管理対象から外すか」というパターン(ルール)を書きます。

Gitはファイルをステージングする際に、このルールと照らし合わせてマッチしたものを無視します。

ここで重要なのは、.gitignoreは「まだGitに追加されていないファイル」にだけ効くという点です。

既にコミット済みのファイルは、.gitignoreに追記しても自動では消えません。

この扱いの違いが、運用時のポイントになります。

Pythonプロジェクトで.gitignoreが重要な理由

Pythonでは、プログラムを実行するだけでキャッシュファイルや一時ファイルが自動生成されます。

さらに、仮想環境をプロジェクトごとに作成することが一般的なため、ディレクトリ内には大量の依存パッケージが展開されます。

これらを誤ってGitに含めてしまうと、次のような問題が起きます。

• リポジトリサイズが無駄に肥大化し、クローンやプルに時間がかかる
• 差分や履歴にノイズが増え、本当に確認したいコードの変更が埋もれてしまう
• 機密情報が含まれた設定ファイル(認証情報やAPIキーなど)を公開リポジトリに上げてしまうリスクが高まる

特にPythonではAPIキーやパスワードを.envファイルで管理するケースが多く、この扱いを誤るとセキュリティ事故につながります。

そのため、Pythonプロジェクトでは、最初に.gitignoreを整えることが必須の作業と言えます。

Pythonで必ず除外すべきファイル一覧

Pythonのコンパイルファイル(pycache, .pyc)の除外

Pythonファイルを実行すると、パフォーマンス向上のために.pyc形式のバイトコードファイルが__pycache__ディレクトリに自動生成されます。

これらは実行環境ごとに再生成されるものであり、ソースコードさえあればいつでも作り直せる中間生成物です。

したがって、.gitignoreには次のようなルールを必ず記述します。

# Pythonのバイトコードキャッシュを除外
__pycache__/
*.py[cod]
*$py.class

上記ではディレクトリ__pycache__そのものと、拡張子が.pyc, .pyo, .pydとなるファイルをまとめて除外しています。

こうすることで、実行するたびに増えていくキャッシュによってGit履歴が汚れることを防げます。

仮想環境(venv, .venv)ディレクトリを.gitignoreに追加

Pythonでは、プロジェクトごとの依存関係を分離するためにvenvや.venvといった仮想環境ディレクトリを作成するのが一般的です。

この中にはインストールしたパッケージとPython本体に紐づく大量のファイルが格納されます。

これらはrequirements.txtやpyproject.tomlから再現可能であり、Gitで管理する必要はありません。

むしろコミットしてしまうと、リポジトリサイズが極端に増え、クローン時間が長くなる原因になります。

.gitignoreには以下のように記述します。

# Python仮想環境の除外
venv/
.venv/
env/
.env/

ここでは、プロジェクトによって異なる仮想環境ディレクトリ名を想定して、複数の候補を列挙しています。

自分のプロジェクトで採用する名称だけを残しても問題ありませんが、テンプレートとしては代表的な名前をすべてカバーしておくと安心です。

環境設定ファイル(.envなどの機密情報)を除外

PythonでWebアプリやバッチ処理を開発する際、環境変数をまとめた.envファイルを利用することが多くあります。

この中にはデータベースの接続情報やAPIキーなど、外部に絶対に漏らしてはいけない機密情報が含まれることが一般的です。

そのため、.gitignoreには必ず次のような設定を入れておきます。

# 機密情報を含む環境設定ファイルを除外
.env
*.env
.env.*

このようにワイルドカードも併用しておくことで、.env.developmentや.env.productionといった名前のファイルもまとめて除外できます。

また、機密情報を含む可能性があるconfig.jsonやsettings_local.pyのようなファイルを使っている場合も、そのプロジェクト固有のルールとして.gitignoreに追記しておくと安全です。

OS依存ファイル(.DS_Storeなど)の除外

開発マシンのOSによっては、フォルダを開いただけで隠しファイルが自動生成されます。

macOSの.DS_Storeや、WindowsのThumbs.db, desktop.iniが代表例です。

これらは見た目の設定やサムネイルキャッシュにすぎず、プロジェクトの中身とは全く関係がありません。

しかし、そのままにしておくと不意にコミット対象に現れ、チームメンバー同士で不要な差分が生じます。

そのため、.gitignoreに以下のようなOS依存ファイルの除外ルールを入れておきます。

# macOSのファインダー設定ファイル
.DS_Store

# Windowsのサムネイル・設定ファイル
Thumbs.db
ehthumbs.db
Desktop.ini

複数OSで開発しているチームでは、全員が同じ.gitignoreを共有することで、プラットフォーム差によるノイズを抑えられるようになります。

IDE設定ファイル(.vscode, .ideaなど)の除外

Python開発では、VS CodeやPyCharmなど様々なIDE・エディタが利用されます。

これらのツールは、プロジェクトフォルダ内に.vscode/や.idea/といった設定用ディレクトリを自動で作成することがあります。

これらの設定にはユーザーごとのパスや拡張機能設定など、個人環境に依存する情報が含まれるため、そのままコミットするとチームメンバー間で不必要なコンフリクトが発生しがちです。

多くのケースでは、IDE設定は各自のローカル環境で完結させる方が運用しやすいため、以下のように.gitignoreで除外することが推奨されます。

# VS Codeの設定ディレクトリ
.vscode/

# JetBrains系IDE(PyCharmなど)の設定ディレクトリ
.idea/

# その他エディタ固有の設定例
*.iml
.vs/

ただし、プロジェクト共通の推奨設定だけを限定的に共有したい場合は、.vscode内の特定のファイルだけをコミットするといったポリシーを取ることもあります。

その場合は、個別ファイル単位で除外設定を調整します。

ログファイル(.log)や一時ファイル(temp)の除外

アプリケーションを動かしていると、動作記録として.logファイルが生成されたり、一時的な作業ファイルがtmp/やtemp/ディレクトリに作られたりします。

これらは実行時にのみ意味を持つもので、コード管理の対象とは別物です。

そのため、以下のようなルールを.gitignoreに追加しておきます。

# ログファイル
*.log
logs/
log/

# 一時ファイル・作業ディレクトリ
tmp/
temp/
*.tmp

アプリが吐き出すログの中には、場合によってはエラーメッセージや内部情報が詳細に記録されていることもあります。

こうしたログも原則としてリポジトリに含めない方が、安全かつクリーンに運用できます。

Python向け.gitignoreの書き方とテンプレート

基本的な.gitignore記述ルール

.gitignoreでは、ファイル名やパスをシンプルなパターンで指定していきます。

基本ルールを押さえておくと、Python以外の用途でも応用がききます。

代表的な書き方は次の通りです。

# コメント行は行頭に # を付ける
# これは説明用のコメントです

# 特定のファイル名
secret.txt

# 拡張子ごとにまとめて除外
*.pyc
*.log

# ディレクトリを丸ごと除外
__pycache__/
venv/

# サブディレクトリも含めてパターン適用
**/__pycache__/

# 否定パターン: 直前までのルールで除外された中から、これは含める
logs/*
!logs/README.md

ポイントを整理すると、次のようになります。

• 行頭の#はコメントとして扱われ、説明を書いてもGitは無視します。
• は任意の文字列にマッチします。例えば.logは全ての.logファイルを対象とします。
• ディレクトリを指定するときは、末尾を/で終わらせるのが慣習です。
• 行頭に!を付けると、それまでのルールで除外された中から例外的に含めたいファイルを指定できます。

Pythonプロジェクトの.gitignoreでは、これらのルールを組み合わせて、「自動生成されるが開発に不要なもの」を的確に除外していきます。

Pythonプロジェクト用.gitignoreテンプレート例

ここまでの内容を踏まえて、汎用的に使えるPython向け.gitignoreテンプレートを示します。

プロジェクトを新規作成したときには、まずこのひな形を配置してから、必要に応じてプロジェクト固有のルールを足していくのがおすすめです。

# ============================
# Python キャッシュ・ビルド関連
# ============================

# バイトコードキャッシュ
__pycache__/
*.py[cod]
*$py.class

# ビルド・配布関連
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
share/python-wheels/
*.egg-info/
.installed.cfg
*.egg
MANIFEST

# Cython, C拡張のビルド結果
*.so
*.pyd
*.dll

# ============================
# 仮想環境
# ============================

venv/
.venv/
env/
.env/
venv.bak/
env.bak/

# pipenv
pipenv/
Pipfile.lock

# poetry
.poetry/
poetry.lock

# ============================
# 環境設定・機密情報
# ============================

.env
*.env
.env.*
*.secret
secrets.json

# 開発用ローカル設定
settings_local.py
config_local.py

# ============================
# ログ・一時ファイル
# ============================

*.log
log/
logs/
tmp/
temp/
*.tmp
*.bak
*.swp
*.swo

# Jupyter Notebook チェックポイント
.ipynb_checkpoints/

# ============================
# OS 依存ファイル
# ============================

# macOS
.DS_Store
.AppleDouble
.LSOverride

# Windows
Thumbs.db
ehthumbs.db
Desktop.ini

# ============================
# IDE / エディタ設定
# ============================

# VS Code
.vscode/

# JetBrains (PyCharmなど)
.idea/
*.iml

# Visual Studio
.vs/

# その他一般的なエディタ
*.sublime-project
*.sublime-workspace

# ============================
# その他
# ============================

# mypy, pytest, coverage などのキャッシュ類
.mypy_cache/
.pytest_cache/
.coverage
htmlcov/
.cache/

このテンプレートは、Pythonプロジェクトの多くのケースをカバーできる汎用的な構成になっています。

実際のプロジェクトでは、ここにDjangoやFlaskなど、利用しているフレームワーク特有の除外設定を追加していく形になります。

DjangoやFlaskなどフレームワーク別の.gitignore例

Django向け.gitignore追加例

Djangoプロジェクトでは、マイグレーションや静的ファイルなど、開発スタイルによっては除外したい対象が増えます。

以下は、先ほどのテンプレートに追加で書き足すイメージの例です。

# Django 特有のファイル・ディレクトリ

# Django マイグレーション (必要に応じて)
# 一般的にはマイグレーションは共有するため ignore しないことが多いが、
# プロトタイピング時などで一時的に除外したい場合に使う
# */migrations/
# */migrations/*.py
# !*/migrations/__init__.py

# メディアファイル (ユーザーアップロード)
media/

# 収集済み静的ファイル (collectstatic の出力)
staticfiles/
static_root/

# SQLite データベース (開発環境専用の場合に限る)
db.sqlite3
*.sqlite3

DjangoではマイグレーションファイルをGitで管理するのが一般的なベストプラクティスです。

ただし、個人学習や試作プロジェクトでは、あえて除外したい場面もあるため、その場合はコメントアウトを外して使うようにします。

Flask向け.gitignore追加例

Flaskでは、アプリケーションインスタンス用のディレクトリや開発用データベースファイルを除外対象にすることがあります。

# Flask 特有のファイル・ディレクトリ

# インスタンスフォルダ (設定や一時ファイルを格納)
instance/
*.db
*.sqlite
*.sqlite3

# Flask-Security などが生成する一部のキャッシュ・ログ
flask_session/

Flaskアプリでも、本番環境ではデータベースを別サーバに置くことが多いため、ローカル開発用のSQLiteファイルはGitから外しておくのが無難です。

その代わり、マイグレーションツール(例: Flask-Migrate, Alembic)のスクリプトはしっかりバージョン管理します。

.gitignore運用のベストプラクティス

既にコミット済みの不要ファイルを削除する手順

.gitignoreはこれからGitに追加されるファイルに対してのみ有効です。

そのため、既にコミットしてしまった__pycache__やvenv/などを後から.gitignoreに書き加えても、自動では履歴から消えてくれません。

このような場合は、次の手順で「リポジトリからは削除するが、ローカルには残す」という操作を行います。

# 1. まず .gitignore を編集し、除外したいパターンを追加する
#    例: __pycache__/ や venv/ など

# 2. Git が現在トラッキングしている不要ファイルをキャッシュから削除
git rm -r --cached __pycache__ venv

# 3. 変更をコミット
git commit -m "Remove cache and venv from repository and update .gitignore"

# 4. リモートにも反映
git push

git rm --cachedを使うことで、リポジトリからはファイルが削除されますが、ローカルディスク上の実ファイルは残ることが重要です。

その後の変更は.gitignoreのルールに従って無視されるようになります。

プロジェクト開始時に.gitignoreを用意する重要性

新しいPythonプロジェクトを始めるときには、初回コミットの前に.gitignoreを作成しておくことが非常に重要です。

最初にこれを怠ると、

• うっかり.envやdb.sqlite3をコミットしてしまう
• __pycache__やvenv/が履歴に残り続ける
• 後から不要ファイルを消す際に、履歴が大きく書き換わる

といった問題に直面しやすくなります。

特にチーム開発や公開リポジトリでは、一度でも機密情報をコミットすると、その履歴が完全に消せない場合があるため、最初から.gitignoreを整備して「そもそもコミットさせない」状態を作ることが、安全な運用につながります。

チーム開発での.gitignore共有と管理ポイント

チーム開発では、.gitignoreはリポジトリの一部としてコミットし、メンバー全員で共有するのが基本です。

このとき、次のようなポイントを意識すると運用がスムーズになります。

まず、プロジェクト共通のルールと、個人の好みや環境依存の設定を分けて考えることが大切です。

Pythonキャッシュや仮想環境、.envなど「誰が見ても除外すべきもの」は共通.gitignoreに書きます。

一方、エディタの細かい設定や一時的な作業ファイルは、各自が~/.gitignore_globalなどのグローバル設定に記述する選択肢もあります。

また、.gitignoreの変更も通常のコードと同じようにプルリクエストやレビューの対象にすることで、「うっかり必要なファイルまで除外してしまう」といった事故を防げます。

特にフレームワークのマイグレーションファイルや設定ファイルなどは、除外可否にチームの合意が必要なケースが多いため、事前に方針を決めておくとよいでしょう。

まとめ

Pythonプロジェクトでは、実行するだけで__pycache__や.pyc、仮想環境、ログ、.envなど多くの不要ファイルが生成されます。

.gitignoreを適切に整備することで、これらをGitの管理対象から外し、履歴をクリーンに保つことができます。

特に、機密情報を含む.envや巨大なvenvディレクトリを誤ってコミットしないためにも、プロジェクト開始時にテンプレートを基に.gitignoreを用意し、チーム全体でルールを共有することが重要です。

今回紹介したテンプレートやフレームワーク別例をベースに、自分のプロジェクトに合った.gitignoreを整えて、安全で快適なPython開発環境を構築してください。