こんにちは、テックリードの私だ。
Pythonでの大規模なバックエンド開発、あるいは長期間稼働するデータ処理パイプラインを設計していると、避けて通れないのが「メモリリーク（Memory Leak）」という名の幽霊だ。
「なぜかコンテナがOOM Killer（Out of Memory Killer）に強制終了される」「プロセスを重ねるごとにRSS（Resident Set Size）が右肩上がりに膨れ上がる」。この現象に直面したとき、多くのエンジニアは焦って `tracemalloc` を仕込み、再デプロイを繰り返す。
だが、待ってほしい。
本番同等の挙動を示すステージング環境や、手元のコンテナ環境で、「今、メモリ上で何が生き残っているのか」をピンポイントで突き止め、その参照チェーンをその場で断ち切る方法を知っていれば、デバッグのスピードは桁違いに跳ね上がる。
今回は、Python標準のデバッガである `pdb`（あるいは拡張版の `ipdb`）と、ガベージコレクションを司る `gc` モジュールを極限まで組み合わせ、メモリリークの根源を暴き出すプロの実践テクニックを伝授する。
—
1. なぜ `pdb` × `gc` なのか？（アーキテクトの視点）
Pythonのメモリ管理は、基本的には参照カウント方式（Reference Counting）と、循環参照（Circular Reference）を回収するための世代別ガベージコレクタ（`gc` モジュール）によって行われている。
メモリリークの本質は、「プログラマの意図に反して、不要になったオブジェクトの参照カウントが0にならない、あるいは循環参照の輪から外れずに孤立している」ことだ。
`tracemalloc` は「どこでメモリが割り当てられたか（Allocated at）」を教えてくれるが、「なぜ今、それがメモリに居座り続けているのか（Who is referencing this?）」という動的な関係性は教えてくれない。
ここで `pdb` の出番だ。ブレークポイントで処理を止め、その場で `gc` モジュールをインポートしてメモリ空間を直接スキャンすれば、「現在Pythonのヒープ上に存在する全オブジェクトのインスタンス」にアクセスし、誰がそいつを掴んでいるのかを完全にトレースできる。
—
2. 開発スピードを劇的に高める `pdb / ipdb` の環境構築
まず、素の `pdb` だけでは長時間のデバッグや複雑なデータ構造の視覚化で消耗する。チーム全体の生産性を底上げするために、以下のツールチェーンをプロジェクトの標準装備として強制しよう。
必須の神プラグインと `.pdbrc` の共有
Pythonプロジェクトのルートディレクトリに `.pdbrc`（または `.ipdbrc`）を配置し、チーム全員のデバッグ体験を統一する。これにより、毎回決まり切ったボイラープレートコマンドを打つ手間をゼロにする。
以下に、実務で即座に使える `.pdbrc` のベストプラクティスを示す。
==============================================================================
親愛なるチームメンバーへ：pdb/ipdbの初期化設定ファイル (.pdbrc)
このファイルはプロジェクトルートに配置し、git管理下に置くこと。
デバッグセッションが開始された瞬間に、強力なエイリアスとカラー設定が有効化される。
=============================================================================
エイリアス定義：タイポを防ぎ、調査スピードを極限まで高める
現在のスコープの変数をきれいに整形して表示する (pprintのエイリアス)
alias pp ppr
実行中のオブジェクトの型を瞬時に確認する
alias t type(%1)
【最重要】現在メモリ上に存在する特定のクラスのインスタンス数を数えるワンライナー
使用法: count_obj MyClass
alias count_obj import gc; print(len([o for o in gc.get_objects() if type(o).__name__ == ‘%1’]))
【最重要】特定のオブジェクトを指し示している「親（参照元）」をリストアップする
使用法: referrers my_variable
alias referrers import gc; [print(type(r), id(r)) for r in gc.get_referrers(%1)]
画面の見やすさを最大化（ipdb使用時は自動適用されるがpdbのフォールバック用）
set autoindent
set arglist
チーム開発における設定共有化ルール
1. `pyproject.toml` や `setup.cfg` への統合: デバッグツールの設定はリポジトリに同梱し、`poetry` や `pipenv` を使ったセットアップ時に開発者間で完全な互換性を保つ。
2. `breakpoint()` の積極的活用: Python 3.7以降で標準化された `breakpoint()` をコードに埋め込み、環境変数 `PYTHONBREAKPOINT=ipdb.set_trace` を `.env` や Dockerfile のデフォルトに指定する。これにより、素の `pdb` からリッチな `ipdb` へシームレスに移行できる。
—
3. 実践：`gc.get_objects()` と `pdb` を駆使したメモリリーク追跡術
では、実際にメモリリークが発生しているシナリオを想定しよう。
あるAPIリクエストやバッチ処理の実行後、特定のカスタムクラス `HeavyResource` のインスタンス数がなぜか減らない（解放されない）というバグに直面したとする。
ステップ1：怪しい地点でブレークし、メモリ上のオブジェクトをキャッチする
リークが疑われる処理の終端、あるいはガベージコレクションを実行した直後に `breakpoint()` を仕掛け、デバッガーを起動する。
import gc
from myapp.models import HeavyResource
def process_batch(items):
resources = [HeavyResource(item) for item in items]
# 何らかの処理…
# 処理が終わったのでリストをクリアしたつもり…だが？
del resources
# ガベージコレクションを強制実行（循環参照の回収）
collected = gc.collect()
print(f”Collected objects: {collected}”)
# デバッガー起動
breakpoint()
pdb（あるいはipdb）のプロンプトが立ち上がったら、ここからが腕の見せ所だ。
ステップ2: `gc.get_objects()` で生存を確認する
デバッガー上で、現在Pythonのガベージコレクタが追跡しているすべてのオブジェクトの中から、目的のクラスを探す。
(Pdb) import gc
(Pdb) # メモリ上に生き残っている HeavyResource のインスタンスを全取得
(Pdb) heavy_objs = [obj for obj in gc.get_objects() if isinstance(obj, HeavyResource)]
(Pdb) print(len(heavy_objs))
5 <-- 「あれ？ リストを消したのに、なぜか5個残っているぞ...？」
ステップ3: 誰がそいつを掴んでいるのか？（`gc.get_referrers()` の活用）
ここからがメモリリーク追跡の核心だ。残存しているオブジェクトの1つをターゲットにし、「誰がそのオブジェクトへの参照を保持しているのか（＝参照元）」を調べる。
(Pdb) target = heavy_objs[0]
(Pdb) # このオブジェクトを参照している親オブジェクトをリストアップ
(Pdb) refs = gc.get_referrers(target)
(Pdb) for r in refs: print(type(r), id(r))
出力結果から、ある `dict`（辞書型）オブジェクトがこの `HeavyResource` を掴んでいることが判明した。さらに深掘りする。その辞書の中身を見てみよう。
(Pdb) # refs[0] が怪しいdictだと仮定して中身を覗く
(Pdb) import pprint
(Pdb) ppr(refs[0])
{‘cache_key_99’:
犯人はグローバル（あるいはモジュールレベル）のキャッシュ辞書だった！
「処理が終わったら解放される」と開発者が思い込んでいたが、モジュール内のグローバル変数 `_CACHE = {}` にデータが永続的に格納され続けていたため、参照カウントが落ちず、メモリリークを引き起こしていた――これが、pdbとgcモジュールを駆使することで、数分で導き出された結論だ。
—
4. 循環参照の元凶を暴く：`gc.garbage` の解析
もう一つのよくある悪夢が「循環参照（Circular Reference）」だ。__del__ メソッド（ファイテナライザ）を定義したオブジェクト同士が互いに参照し合っている場合、PythonのデフォルトのGCはどの順番で解放すべきか判断できず、`gc.garbage` というブラックボックスにそれらを放り込んで放置してしまう。
もしプログラム内で `gc.set_debug(gc.DEBUG_LEAK)` が有効になっているなら、pdbのプロンプトから以下のコマンドを叩くことで、回収できずに迷子になっているオブジェクトのリストを即座に引き出せる。
(Pdb) import gc
(Pdb) # 世代別GCで回収しきれずにゴミ箱行きになったオブジェクトを確認
(Pdb) print(gc.garbage)
[
(Pdb) # なぜ循環しているのか？それぞれの参照先（referents）を可視化する
(Pdb) for obj in gc.garbage:
… print(obj, “-> refs:”, gc.get_referents(obj))
…
このアプローチにより、複雑なORMのモデル間リレーションや、非同期タスクのクロージャ内部で発生した循環参照のループを、ソースコードの海から正確に釣り上げることができる。
—
5. テックリードからの総括：デバッグを「勘」から「科学」へ
多くのエンジニアは、バグに直面したときにとりあえず `print()` を仕込み、やみくもにコードを書き直す。しかし、それはプロフェッショナルのアプローチではない。
`pdb` は単なる「コードを止めて変数を覗くツール」ではない。Pythonのランタイム環境そのものをハックし、メモリの生態系をその場で観測・制御するための手術刀である。
今回紹介した `gc.get_objects()` と `.pdbrc` によるカスタムエイリアスの組み合わせをチームの標準プラクティスとして定着させれば、メモリリークという目に見えない敵に対する恐怖は消え去る。
「なぜメモリリークしているのか」を数秒で特定するエンジニアリングを、あなたのチームにも今すぐ導入してほしい。コードの品質と、チームの開発生産性は、確実に次のステージへと引き上げられる。