Pythonのbreakpoint使い方完全ガイド｜最速でバグ原因を突き止める

2025年9月16日2025年12月21日

Python

Pythonでバグの原因を特定する際に、なんとなくprintで値を表示していないでしょうか。

実は、標準機能のbreakpointを正しく使うことで、処理を途中で止めて状態を自由に観察でき、原因特定のスピードが大きく変わります。

本記事では、Python初心者から実務レベルまで使えるbreakpointの完全ガイドとして、基本からIDEごとの使い方、実践テクニックまで体系的に解説します。

目次 [ close ]

Pythonのbreakpointとは

breakpointの基本概要

Pythonのbreakpointは、プログラムの実行をその場で一時停止し、対話的に中身を調査できる仕組みです。

Python 3.7以降ではbreakpoint()という組み込み関数が用意されており、これをコード中に書くだけで、そこでデバッガが起動します。

この関数が呼ばれると、Pythonは現在のローカル変数やグローバル変数、スタックフレームを保持したまま実行を止め、開発者がその状態を確認したり、1行ずつ実行を進めたりできるようにします。

実行の流れを文章で整理すると次のようになります。

プログラムが上から順に実行され、breakpoint()に到達した瞬間、処理が停止します。

その停止した時点の値や状態をデバッガ経由で調査し、問題を切り分けていきます。

printデバッグとの違い

printデバッグは、処理の途中で変数の値や状態を出力して確認する古典的な手法です。

直感的で覚えやすい一方で、次のような弱点があります。

見たい箇所が増えるほどprint文が増え、コードが読みにくくなる
出力が多くなりすぎて、必要な情報を探しづらい
1回の実行で確認できる情報が限定的で、何度もコードを直して実行し直す必要がある

これに対してbreakpointを使ったデバッグでは、同じ1回の実行で以下のようなことができます。

その時点でのあらゆる変数の値を、その場で自由に参照できる
必要に応じてforループや関数の中を1行ずつ追いかけられる
条件を満たした時にだけ止めるなどの柔軟な制御ができる

同じ「状態を知る」という目的でも、breakpointは対話的に、printは記録的に情報を得る方法だとイメージすると理解しやすいです。

デバッガ(PDB)との関係

Pythonのbreakpoint()は、内部的にはsys.breakpointhookというフック関数を呼び出します。

デフォルトでは、このフックが標準デバッガであるpdb.set_trace()を呼び出すようになっています。

つまり、以下のような関係になります。

コードにbreakpoint()を書く
Pythonはsys.breakpointhook()を呼ぶ
デフォルトではpdb.set_trace()が動き、PDBデバッガが起動する

IDE(VSCodeやPyCharm)は、このsys.breakpointhookを自前のデバッガに差し替えて、GUIでのブレークポイントやステップ実行を実現しています。

まとめると、breakpointは「どのデバッガを起動するかを抽象化したスイッチ」であり、その下で動いている具体的な仕組みがPDBやIDEのデバッガだと理解するとよいです。

breakpointの基本的な使い方

breakpointの書き方と動作の流れ

まずは、もっともシンプルなbreakpointの記述方法を確認します。

最小のサンプルコード

Python

# sample_basic_breakpoint.py

def add(a, b):
    result = a + b
    breakpoint()  # この行で実行が一時停止します
    return result

if __name__ == "__main__":
    total = add(10, 20)
    print("合計:", total)

このスクリプトをターミナルから実行する場合は次のようになります。

Shell

python sample_basic_breakpoint.py

実行すると、breakpoint()に到達した時点でPDBが起動し、ターミナル上で対話的なプロンプトが表示されます。

PDB起動時の画面イメージと基本コマンド

PDBが起動すると、だいたい次のような表示になります。

> /path/to/sample_basic_breakpoint.py(5)add()
-> return result
(Pdb)

ここで、いくつか代表的なコマンドを覚えておくと便利です。

p 変数名 : 変数の中身を表示する(p resultなど)
n : 次の行まで実行する(next)
c : 次のブレークポイントまで実行を継続する(continue)
l : 近くのコードを一覧表示する(list)
q : デバッガを終了し、プログラムを止める(quit)

まずはp 変数名とn、cさえ把握しておけば、基本的なデバッグは十分に行えます。

条件付きbreakpoint

単に「この行に来たら止める」というだけでなく、特定の条件を満たした場合だけ停止したいことはよくあります。

例えば、ループの中で1000回に1回だけ値がおかしくなる、といった状況です。

Pythonでは、条件付きのブレークポイントをいくつかの方法で実現できます。

if文とbreakpointを組み合わせる

もっとも簡単なやり方は、if文で条件を囲んでからbreakpoint()を呼ぶ方法です。

Python

# sample_conditional_breakpoint_simple.py

def process_numbers(numbers):
    for i, value in enumerate(numbers):
        # 例えば、100を超える値が現れた時だけデバッガを起動したいケース
        if value > 100:
            breakpoint()  # 条件を満たした時だけ停止
        # 本来の処理(ここでは単純に表示)
        print(i, value)

if __name__ == "__main__":
    data = [10, 20, 30, 150, 40, 200]
    process_numbers(data)

このコードでは、値が100を超えた時にだけbreakpointが起動し、その時点でのiやvalueの値を確認できます。

PDB側で条件付きブレークポイントを設定する

ターミナルでPDBを使う場合、bコマンドでブレークポイントを設定し、そこに条件を埋め込むこともできます。

(Pdb) b sample_conditional_breakpoint_simple.py:6, value > 100
Breakpoint 1 at sample_conditional_breakpoint_simple.py:6

これは「6行目に、value > 100が真のときだけ効くブレークポイントを設定する」という意味になります。

コードにifを増やしたくない場合に有効な方法です。

コードに手を入れられるならif ...: breakpoint()、動いているプロセスをその場で調査したいならPDBの条件付きブレークポイントと覚えると整理しやすいです。

ループ処理でのbreakpoint活用法

ループ処理は、バグが紛れ込みやすい部分です。

特に、特定のインデックスや特定のデータパターンでだけ問題が起こる時には、breakpointが非常に役に立ちます。

例: 特定のインデックスでだけ止める

Python

# sample_loop_breakpoint.py

def process(items):
    for idx, item in enumerate(items):
        if idx == 42:  # 42番目の要素でだけ止めたいケース
            breakpoint()
        # 実際の処理(ここでは仮の処理)
        print(f"{idx}: {item}")

if __name__ == "__main__":
    items = list(range(100))
    process(items)

このようにすると、大量のループのうち、特定の1回でだけ状態を詳細に調べることができます。

例: おかしな値が出た時だけ止める

Python

# sample_loop_anomaly_breakpoint.py

def calculate(values):
    for i, v in enumerate(values):
        result = some_complex_calc(v)
        # 結果が負の値になった時だけ調査したい
        if result < 0:
            breakpoint()
        print(i, result)

def some_complex_calc(x):
    # 複雑な計算だと仮定
    return x * 2 - 5

if __name__ == "__main__":
    data = [1, 2, 3, -10, 4, 5]
    calculate(data)

この場合、resultが負になった瞬間に停止し、vやresult、さらにはスタックトレースを確認して、どのようにその値に至ったのかを詳細に追いかけることができます。

関数内・クラス内でのbreakpointの使い方

関数やクラスメソッドの内部は、引数・ローカル変数・インスタンス変数が入り混じるため、デバッグの重要ポイントです。

関数の内部状態を調べる

Python

# sample_function_breakpoint.py

def compute_price(base_price, tax_rate, discount):
    taxed = base_price * (1 + tax_rate)
    final_price = taxed - discount
    breakpoint()  # 計算結果が確定したタイミングで停止
    return final_price

if __name__ == "__main__":
    price = compute_price(1000, 0.1, 50)
    print("最終価格:", price)

この位置にbreakpointを置くことで、base_price、tax_rate、discount、taxed、final_priceといったローカル変数を一度に確認できます。

クラスメソッドでの活用

Python

# sample_class_breakpoint.py

class Order:
    def __init__(self, items):
        self.items = items  # 商品のリスト(単価)
        self.total = 0

    def calculate_total(self, tax_rate):
        subtotal = sum(self.items)
        self.total = int(subtotal * (1 + tax_rate))
        breakpoint()  # selfやsubtotal、tax_rateの状態を確認したい
        return self.total

if __name__ == "__main__":
    order = Order([100, 200, 300])
    total = order.calculate_total(0.1)
    print("合計金額:", total)

PDB上ではselfも普通の変数として扱えるため、p self.itemsやp self.totalのように入力して、インスタンスの内部状態を詳細に確認できます。

実務で役立つbreakpoint活用テクニック

エラー発生箇所を最速で特定する手順

実務で多いのは、すでにエラーが発生していて、その原因をできるだけ早く突き止めたいというケースです。

この場合、以下のステップでbreakpointを活用すると効率的です。

まずはエラーを再現し、表示されるトレースバック(エラーメッセージ)を確認します。最後に表示されているファイル名と行番号が、直接エラーになった箇所です。
そのファイルの該当行、もしくは少し前(直前の値が決まる行)にbreakpoint()を追加します。
プログラムを再度実行し、同じ操作でエラー直前の状態まで進めます。breakpointで停止したら、PDBやIDEのデバッガでローカル変数や引数の値を確認します。
必要に応じて、そのまま1行ずつステップ実行し、どの時点で想定外の値に変わるかを追跡します。

この手順を徹底することで、「なんとなく動かない」を「どの変数のどの値がおかしいか」まで素早く落とし込むことができます。

大規模コードでのbreakpointの挿入ポイント

大規模なプロジェクトになると、どこにbreakpointを置くべきか迷うことが増えます。

このときは、「入力」と「出力」と「境界」に着目すると整理しやすくなります。

典型的な挿入ポイントとしては、次のような場所が考えられます。

APIハンドラやコントローラなど、外部からリクエストが入る入り口
DBアクセスや外部サービス呼び出しなど、システムの境界
集約されたビジネスロジックを持つサービス層のメソッド入口・出口
複雑な条件分岐や計算ロジックの前後

例えばWebアプリケーションであれば、次のようなイメージです。

Python

# views.py などのWebハンドラ例(フレームワークは仮想的なもの)

def create_order(request):
    # 1. リクエストの検証
    # breakpoint() を入れる候補: リクエストパラメータを確認したいとき
    # breakpoint()

    # 2. ビジネスロジック呼び出し
    order = order_service.create_order(request.user_id, request.items)
    # 3. レスポンス構築
    return to_json(order)

さらに、サービス層のメソッド内部にもbreakpointを置いておくことで、「入ってきた時点でおかしいのか」「ロジックの途中でおかしくなるのか」を一気に切り分けることができます。

ログ出力とbreakpointを組み合わせる方法

ログとbreakpointは対立するものではなく、役割の異なる補完関係にあります。

ログ: 本番環境を含めて、あとから見返せる履歴を記録するもの
breakpoint: 手元の開発環境で、その場で状態を深掘りするための一時的なツール

実務では、次のような組み合わせ方が有効です。

まずログに重要な情報(ユーザーID、処理対象、結果コードなど)を記録しておく
問題が起こったら、ログから再現に必要な条件を特定する
その条件でローカル環境を再現し、問題が疑われる箇所にbreakpoint()を設置
ログだけではわからない詳細な内部状態を、breakpointでピンポイントに調査する

ログ出力にはloggingモジュールを使い、breakpointはあくまでローカルでの調査用、と役割分担をはっきりさせておくと運用しやすくなります。

テストコードとbreakpointの連携

ユニットテストや統合テストが整備されているプロジェクトでは、テスト実行中にbreakpointを起動する手法が非常に強力です。

テストケースは「特定の入力と期待される結果」が整理されているため、再現性の高いデバッグができます。

pytestとbreakpoint

pytestなどのテストランナーでテストを実行している場合でも、テスト対象のコードにbreakpoint()を仕込めば、テスト実行中にデバッガが立ち上がります。

Python

# app.py

def divide(a, b):
    result = a / b
    breakpoint()  # テストで不正値が入るケースを調べたい
    return result

Python

# test_app.py

from app import divide

def test_divide_zero():
    # ここではゼロ除算が起こるケースを想定
    divide(10, 0)

この状態で次のように実行すると、例外が発生する直前でbreakpointが起動します。

Shell

pytest -q

テスト経由でバグが再現できる場合は、必ずテストからデバッグを開始すると決めておくと、再現条件や期待値が明確になり、原因特定が一気に楽になります。

IDE別のbreakpoint設定とデバッグ

VSCodeでのbreakpointの使い方

VSCodeは、Python拡張機能を入れることで強力なデバッガが利用できます。

GUIで行番号の左側をクリックしてブレークポイントを設定できるため、ターミナルでPDBを操作するより直感的に扱えます。

基本的な手順

Microsoft製の「Python」拡張機能をインストールします。
デバッグしたいPythonファイルを開きます。
停止したい行の左側(行番号の左)をクリックすると、赤い丸が表示されます。これがブレークポイントです。
左サイドバーの「実行とデバッグ」(再生アイコン)から「Pythonファイル」などを選んで起動します。
実行がブレークポイントに到達すると、自動的にそこで一時停止し、変数の中身やコールスタックがGUIで確認できます。

条件付きブレークポイントやログポイント

VSCodeでは、赤いブレークポイントアイコンを右クリックすることで、次のような高度な設定も行えます。

条件式: 「i == 42」のような条件を満たした時だけ停止
ヒットカウント: 「100回目に到達した時だけ止める」
ログポイント: 停止せずに、指定したメッセージだけを出力する

これにより、ループの大量の繰り返しのうち特定の回だけをデバッグするなどの使い方が容易になります。

PyCharmでのbreakpointの使い方

PyCharmも、Python向けに最適化されたリッチなデバッガを備えています。

基本的な操作感はVSCodeと似ていますが、ブレークポイントごとの詳細なオプションや式の評価機能が充実しています。

基本操作

エディタの行番号の左をクリックして赤い丸(ブレークポイント)を設定します。
右上の「Debug」ボタン(虫のアイコン)をクリックしてデバッグ実行します。
停止すると、下部の「Debug」ツールウィンドウにVariables(変数一覧)やWatches(監視式)、Console(デバッグコンソール)が表示されます。

実務で便利な機能

PyCharmには、次のような機能が備わっています。

条件付きブレークポイント: 条件式を入力して、特定の場合だけ止める
Evaluate Expression: 実行を止めた状態で任意のPython式を評価して結果を確認
スマートステップイン: ラインに複数の関数呼び出しがある場合、どの関数に入るかを選択

これらを駆使することで、複雑なビジネスロジックや大量データ処理でも、必要な地点にピンポイントで焦点を当てたデバッグができるようになります。

ターミナル(PDB)でのbreakpointの使い方

IDEがない環境や、サーバー上でのデバッグでは、標準のPDBを使う場面も多くあります。

ここではターミナルだけで完結するPDBの基本的な使い方を整理します。

2つの起動方法

コード中にbreakpoint()を書き、通常通りpython script.pyで実行する
直接PDBからスクリプトを起動する

Shell

python -m pdb script.py

2つ目の方法では、breakpoint()を書かなくても、PDBのbコマンドで任意の行にブレークポイントを設定できます。

よく使うPDBコマンドまとめ

PDBの代表的なコマンドを簡単な表にまとめます。

コマンド	意味	使用例
l	近くのソースを表示	`l`
n	次の行まで実行	`n`
s	関数呼び出しの中に入る	`s`
c	次のブレークポイントまで実行	`c`
p expr	式を評価して表示	`p my_var`
b	ブレークポイントを設定	`b 10` (10行目)
b file:line	別ファイルに設定	`b app.py:42`
cl	ブレークポイント削除	`cl 1` (1番を削除)
q	デバッガ終了	`q`

GUIに比べて学習コストはありますが、その分どんな環境でも同じ操作ができるため、慣れておくと長期的に大きな武器になります。

まとめ

breakpointは、Pythonに標準で備わっている強力かつシンプルなデバッグの入口です。

breakpoint()を1行書くだけで、その地点の変数や状態を自由に観察でき、printデバッグでは得られない深さと柔軟さでバグの原因に迫れます。

PDBやVSCode、PyCharmなど、どのデバッガであっても基本は同じです。

まずはエラー行の直前にbreakpointを置き、1行ずつ状態を確認する習慣を付けてみてください。

慣れてくれば、条件付きブレークポイントやテストとの連携など、より高度な使い方で、バグ調査の時間を大きく短縮できるようになります。