閉じる

Gitの.gitignore(Python)何を書く？ベストプラクティス集

GitでPythonプロジェクトを始めるとき、最初に迷いがちな点が.gitignoreの中身です。

不要なファイルや秘密情報を誤ってコミットすると後から大変なことになります。

この記事では、Python初心者がまず入れるべき除外ルールと、開発環境別の追加、運用のコツまで丁寧に解説します。

目次 [ close ]
  1. .gitignoreとは？Python初心者の基本
    1. Gitの除外設定の役割
    2. Pythonで無視すべきファイルとは
  2. まず入れる基本ルール
    1. __pycache__と*.pycを除外
    2. build/・dist/・*.egg-infoを除外
    3. テスト/型のキャッシュ(.pytest_cache, .mypy_cache)
    4. キャッシュ全般(.cache など)
  3. 開発環境ごとの除外
    1. 仮想環境を除外(venv/, .venv/)
    2. 秘密情報を除外(.env, .env.local)
    3. エディタ/IDEの設定(.vscode, .idea)
    4. OSの生成物(.DS_Store, Thumbs.db)
    5. Jupyterのチェックポイント(.ipynb_checkpoints)
    6. 大きな一時データ/ログ(logs/, tmp/, outputs/)
  4. テンプレートとベストプラクティス
    1. 最小の.gitignore(コピペ用サンプル)
    2. VSCode/Jupyter併用の例
    3. macOS/Windows向けの追加
    4. 除外しないファイルの例(requirements.txt, README.md)
    5. 既にコミット済みを後から無視するコツ
    6. チームで共有する.gitignoreの運用
  5. まとめ

.gitignoreとは？Python初心者の基本

Gitの除外設定の役割

Gitはフォルダ内の変更をすべて追跡するわけではなく、.gitignoreに書かれたパターンに合致したファイルを無視できます。

これにより、ビルド生成物やキャッシュ、個人環境に依存するファイル、秘密情報などをコミット対象から外すことができます。

目的はリポジトリを「再現に必要なソースコードと設定」だけに保つことです。

Pythonで無視すべきファイルとは

Pythonでは、インタプリタやツールが多数の派生ファイルを生成します。

これらは環境依存か使い捨てなため、通常コミットしません。

以下の観点で考えると迷いにくいです。

  • 実行時に生成される派生物か
  • 開発者のローカル環境に固有か
  • 機微情報を含む可能性があるか
  • 大容量でバージョン管理に不向きか

代表的なものを整理します。

分類例なぜ無視するか
バイトコード/キャッシュ__pycache__/, *.pyc実行環境ごとに差異が出る派生物で再生成可能
ビルド成果物build/, dist/, *.egg-info配布用の生成物でソースから再生成可能
テスト/型チェックのキャッシュ.pytest_cache/, .mypy_cache/開発者ごとの一時データ
ツールのキャッシュ.cache/パッケージマネージャや各種ツールのキャッシュ
仮想環境venv/, .venv/ローカルごとの依存環境。再作成可能
秘密情報.env, .env.localAPIキーやパスワードが含まれるため
エディタ/IDE設定.vscode/, .idea/個人設定が多く、環境依存
OS生成物.DS_Store, Thumbs.dbOSが勝手に作る不要ファイル
Jupyterのチェックポイント.ipynb_checkpoints/ノートブックの自動バックアップ
ログ・一時データlogs/, tmp/, outputs/実験結果や一時ファイルで大容量になりがち

特に.envなどの秘密情報は絶対にコミットしてはいけません。

公開リポジトリに流出すると取り返しがつきません。

まず入れる基本ルール

__pycache__と*.pycを除外

Pythonは実行時にバイトコードキャッシュを生成します。

これは環境依存であり、常に再生成可能です。

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

実演: __pycache__ができる様子

以下は小さなスクリプトを動かして、__pycache__が生成される様子の例です。

Shell
# スクリプトを作成して実行
echo 'print("hello")' > hello.py
python hello.py

# 生成物を確認
ls -a
実行結果
.
.. 
hello.py
__pycache__    # 実行時に生成される

このような生成物は追跡しないのが原則です。

build/・dist/・*.egg-infoを除外

パッケージ配布やビルドで作られる成果物です。

pyproject.tomlやsetup.cfgからいつでも再生成できます。

.gitignore
# パッケージのビルド成果物
build/
dist/
*.egg-info/

テスト/型のキャッシュ(.pytest_cache, .mypy_cache)

テストや型チェックは開発者のローカルで実行され、キャッシュは都度作り直せます。

.gitignore
# テスト/型チェッカーのキャッシュ
.pytest_cache/
.mypy_cache/
.tox/
.coverage
coverage.xml

キャッシュ全般(.cache など)

ツールが作るキャッシュディレクトリは原則として無視します。

.gitignore
# 各種ツールのキャッシュ
.cache/

開発環境ごとの除外

仮想環境を除外(venv/, .venv/)

仮想環境は依存を隔離するためのものです。

requirements.txtやpyproject.tomlなどのメタデータをコミットし、実体は無視します。

再構築はpython -m venv venvやpip install -r requirements.txtで可能です。

.gitignore
# 仮想環境
venv/
.venv/
env/

プロジェクト直下に置くなら<venv/>か<.venv/>に統一すると混乱が減ります。

秘密情報を除外(.env, .env.local)

APIキーやデータベースのパスワードを含むファイルは常に除外します。

共有するときは値を空にした.env.exampleをコミットし、使い方をREADMEに記載します。

.gitignore
# 環境変数ファイル(機微情報)
.env
.env.*
!.env.example   # 雛形は除外しない

エディタ/IDEの設定(.vscode, .idea)

個人のエディタ設定は通常コミット不要です。

プロジェクト推奨設定を共有したい場合は.vscode/extensions.jsonのように限定的に運用し、その他は無視します。

.gitignore
# エディタ/IDE
.vscode/
.idea/

OSの生成物(.DS_Store, Thumbs.db)

OSが生成する不可視ファイルは迷わず除外します。

.gitignore
# OS生成物
.DS_Store
Thumbs.db

Jupyterのチェックポイント(.ipynb_checkpoints)

Jupyterの自動バックアップは履歴汚染の原因になります。

.gitignore
# Jupyter
.ipynb_checkpoints/

ノートブック自体(*.ipynb)はコミット対象ですが、大きな出力はなるべく消してから保存すると差分が見やすくなります。

大きな一時データ/ログ(logs/, tmp/, outputs/)

実験結果やログは肥大化しやすいので除外します。

再現に必要な最小限のサンプルデータのみを小さく同梱し、必要に応じてGit LFSや外部ストレージを検討します。

.gitignore
# ログ・一時・実験出力
logs/
log/
tmp/
outputs/
*.log

テンプレートとベストプラクティス

最小の.gitignore(コピペ用サンプル)

まずはこれだけ入れておけば安全という最小セットです。

プロジェクトに応じて追記してください。

.gitignore
# --- Python 基本 ---
__pycache__/
*.py[cod]
*$py.class

# --- パッケージング ---
build/
dist/
*.egg-info/

# --- テスト/型/ツール ---
.pytest_cache/
.mypy_cache/
.cache/
.tox/
.coverage
coverage.xml

# --- 仮想環境 ---
venv/
.venv/
env/

# --- 秘密情報 ---
.env
.env.*
!.env.example

# --- エディタ/IDE ---
.vscode/
.idea/

# --- OS生成物 ---
.DS_Store
Thumbs.db

# --- Jupyter ---
.ipynb_checkpoints/

# --- ログ/一時/出力 ---
logs/
tmp/
outputs/
*.log

VSCode/Jupyter併用の例

VSCodeの推奨拡張だけ共有したい場合は、.vscode/extensions.jsonは許可し、その他は除外します。

Jupyterはチェックポイントのみ除外します。

.gitignore
# VSCode: workspace設定は原則除外。ただし拡張の推奨は許可
.vscode/*
!.vscode/extensions.json

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

# そのほかPython基本セット
__pycache__/
*.py[cod]
*$py.class
.pytest_cache/
.mypy_cache/
.cache/
venv/
.venv/
.env
.env.*
!.env.example

macOS/Windows向けの追加

OS固有のゴミファイルを広めにカバーします。

.gitignore
# macOS
.DS_Store
.AppleDouble
.LSOverride
Icon?
._*

# Windows
Thumbs.db
ehthumbs.db
Desktop.ini
$RECYCLE.BIN/

除外しないファイルの例(requirements.txt, README.md)

再現性のために残すべきファイルがあります。

以下はコミット推奨です。

  • requirements.txt or pyproject.tomlとpoetry.lock/requirements.lockの類
  • README.mdやCONTRIBUTING.mdなどのドキュメント
  • リンターやテストの設定(pyproject.toml, setup.cfg, pytest.ini, mypy.iniなど)
  • サンプル環境変数の雛形(.env.example)
  • 小さなサンプルデータ(data/sample.csvなど、サイズは数十KB〜数百KB目安)

「必要になるが機密でない」「再生成できない」ものはコミットという観点で判断します。

既にコミット済みを後から無視するコツ

すでに履歴に入ってしまったファイルは、.gitignoreに追加しただけでは消えません。

インデックスから取り除き、以後は無視させます。

Shell
# 例: venv/ と .env を今後は無視したい
echo -e "venv/\n.env" >> .gitignore

# 既に追跡中のファイルをインデックスから外す(作業ツリーは残す)
git rm -r --cached venv .env

# 変更をコミット
git add .gitignore
git commit -m "Ignore venv and .env going forward"
実行結果
rm 'venv/bin/activate'
rm '.env'
[main 1234abc] Ignore venv and .env going forward
 2 files changed, 2 insertions(+)
 delete mode 100644 .env
 delete mode 100644 venv/bin/activate

履歴から完全に消したい場合はgit filter-repoやgit filter-branch、GitHubならgit filter-repoの利用を検討しますが、公開済みの秘密情報は必ずキーを再発行してください。

チームで共有する.gitignoreの運用

チーム開発では、次の指針で運用すると安定します。

  • レイヤー分け
    • リポジトリ共有: プロジェクト共通で無視すべきものを.gitignoreに記載
    • 開発者共通(グローバル): OSやエディタの個人差が大きいものはグローバル除外に回す
Shell
# 一度だけグローバルの除外ファイルを設定
git config --global core.excludesfile ~/.gitignore_global

# 例: グローバルにOSやエディタのゴミを登録
printf ".DS_Store\nThumbs.db\n.vscode/\n.idea/\n" >> ~/.gitignore_global
  • 雛形の共有
    • .env.exampleを用意し、READMEに「cp .env.example .envして値を入れる」と記載
    • CI/CDで必要な最小設定は専用の例ファイルを用意
  • パターンの精度
    • !で例外指定を活用
      例: VSCodeフォルダは無視するが、推奨拡張だけは追跡したい
.gitignore
.vscode/*
!.vscode/extensions.json
  • モノレポや多言語構成
    • サブディレクトリごとの規則が必要なら、ルート.gitignoreにスコープを切る
      例: すべてのサブプロジェクトの仮想環境を除外
.gitignore
**/venv/
**/.venv/
  • 公式テンプレートの活用
    • GitHubの<python>.gitignoreテンプレートをベースに、プロジェクトに必要な最小限を追加
    • 追加は狙いを明確にし、過剰なワイルドカードで必要ファイルを巻き込まない

よくある落とし穴

  • *.envのように広くしすぎて.env.exampleまで無視してしまう
  • outputs/を無視した結果、必要なサンプル出力まで追跡されない
  • .vscode/を丸ごとコミットして個人のパスが混入してビルドが壊れる
  • __pycache__/や*.pycを入れ忘れて差分がノイズだらけになる

迷ったら「再現に必要か」「秘密や個人差を含むか」で判断し、説明できる最小限だけをコミットしましょう。

まとめ

.gitignoreはPythonプロジェクトの健康を守る最初の防波堤です。

__pycache__/や*.pyc、build/・dist/、テストや型チェックのキャッシュ、仮想環境、.envなどの秘密情報、エディタ設定、OS生成物、Jupyterチェックポイント、ログや一時出力を中心に確実に除外しましょう。

さらに、プロジェクトで必要なものは積極的に残し(requirements.txtやpyproject.toml、設定ファイル、ドキュメントなど)、git rm --cachedでの後処理やグローバル除外の併用で運用を整えると安心です。

最後に、秘密情報は一度出たら戻せないという意識を持ち、最小限の追跡と明確なルールでチームの生産性と安全性を高めていきましょう。

Python 実践TIPS - 開発環境とツール
この記事を書いた人
エーテリア編集部
エーテリア編集部

人気のPythonを初めて学ぶ方向けに、文法の基本から小さな自動化まで、実際に手を動かして理解できる記事を書いています。

クラウドSSLサイトシールは安心の証です。

URLをコピーしました！