Pythonのデバッガーpdbの使い方|breakpoint()で止めて変数を調べる
プログラムが思いどおりに動かないとき、print() を何行も書き足して、実行して、消して……を繰り返していませんか。Python には、プログラムを好きな行で一時停止して、そのときの変数を見たり 1 行ずつ進めたりできる「デバッガー」が標準で付いています。それが pdb です。追加のインストールは要りません。
Windows 11 の Python 3.12 で実際に動かした画面((Pdb) のプロンプトや -> の行)をそのまま載せながら、次のことを解説します。
- print デバッグと pdb の違い、
breakpoint()で止める方法 - 主な命令:n・s・c・l・ll・p・pp・w・u・d・b・q
- n(次の行へ)と s(関数の中へ)の違い
py -m pdbで最初から動かす方法と、エラーで止まった場所から調べる方法(事後デバッグ)- 変数 n を表示しようとして次の行へ進んでしまう、などの落とし穴と、
PYTHONBREAKPOINT=0の使い方
載せている画面は、命令を標準入力から流し込んで記録したものに、入力した命令を (Pdb) のあとに書き足して整えたものです。ファイルの場所はユーザー名が入るため c:\work\ に、Python 本体の場所は c:\...\python312\lib\ に置き換えています(Windows の pdb は、ファイルの場所を小文字で表示します)。
pdb とは:print デバッグとの違い
例として、買い物の合計(税込み)を計算するプログラムを使います。ノート 200 円×3 冊とペン 120 円×2 本、税 10% なので、正しい答えは 660 + 264 = 924 のはずです。
def tax(price):
return price * 10 // 100
def total(items):
result = 0
for name, price, qty in items:
print("確認:", name, price, qty, result)
result += price + tax(price) * qty
return result
items = [("ノート", 200, 3), ("ペン", 120, 2)]
print(total(items))
7 行目が、よくある「print デバッグ」です。実行すると次のようになりました。
確認: ノート 200 3 0
確認: ペン 120 2 260
404
答えが 404 で、まちがっています。ノートの分が 260 になっていることは分かりましたが、なぜ 260 なのかを調べるには、また print を書き足して実行し直す必要があります。pdb なら、止めた場所で tax(price) や途中の式をその場でいくつでも計算して確かめられます。
| print デバッグ | pdb | |
|---|---|---|
| 見られる値 | あらかじめ print に書いたものだけ | 止めた場所の変数・式を何でも |
| 見たい値が増えたとき | 書き足して実行し直し | その場で p 命令を打つ |
| 処理の流れ | 出力の順番から推測する | 1 行ずつ進めて目で追える |
| 後始末 | print を消し忘れやすい | breakpoint() を消し忘れると、そこで止まる(後述) |
| 向いている場面 | 値を 1〜2 個見れば分かるとき、止められない処理 | 原因の見当がつかないとき、関数をまたぐ処理 |
どちらが正しいというものではありません。動作の記録を残したいなら print ではなく logging を使います(「Pythonのloggingの使い方」参照)。この記事では「その場で調べる」道具としての pdb を解説します。
breakpoint() で止める
止めたい場所に breakpoint() と 1 行書きます。Python 3.7 で追加された組み込み関数で、それより前の書き方 import pdb; pdb.set_trace() と同じ働きです。さきほどの print の行を置き換えて、calc.py として保存します。
def tax(price):
return price * 10 // 100
def total(items):
result = 0
for name, price, qty in items:
breakpoint()
result += price + tax(price) * qty
return result
items = [("ノート", 200, 3), ("ペン", 120, 2)]
print(total(items))
ふつうに実行します。
py calc.py
プログラムが止まり、(Pdb) というプロンプト(入力待ちの印)が出ます。ここで命令を入力して Enter を押します。p は「値を表示する」命令です。
> c:\work\calc.py(8)total()
-> result += price + tax(price) * qty
(Pdb) p name, price, qty
('ノート', 200, 3)
(Pdb) p tax(price)
20
(Pdb) p price + tax(price) * qty
260
(Pdb) p (price + tax(price)) * qty
660
(Pdb) q
税額 tax(price) は 20 で正しいのに、式全体は 260 です。* は + より先に計算されるため、「200 + 20×3」になっていました。かっこを付けた式なら 660 になることも、その場で確かめられました。8 行目を result += (price + tax(price)) * qty に直せば 924 になります。
止まったときの表示の読み方
> c:\work\calc.py(8)total():ファイル名(行番号)関数名。いま calc.py の 8 行目、total 関数の中にいる-> result += ...:次に実行する行。この行はまだ実行されていない- breakpoint() を書いた 7 行目ではなく、そのすぐ次の 8 行目で止まる
「-> の行はまだ実行されていない」は大事なポイントです。この時点で result を表示すると、8 行目を足す前の値が出ます。
主な命令の一覧
命令は 1〜2 文字に省略できます。公式ドキュメントでは n(ext) のように、かっこの外が省略形です(n か next のどちらでもよく、途中の ne は使えません)。
| 命令 | 働き |
|---|---|
| n(next) | 次の行まで進める。関数の呼び出しは中に入らず、まとめて実行する |
| s(step) | 1 歩進める。関数を呼ぶ行なら、その関数の中に入って止まる |
| r(return) | 今いる関数が終わる(return する)まで進める |
| c(continue) | 次のブレークポイントまで実行を続ける |
| l(list) | 今の行の前後 11 行を表示する |
| ll(longlist) | 今いる関数のソースを全部表示する |
| p 式 | 式の値を表示する |
| pp 式 | 式の値を整形(pprint)して表示する |
| a(args) | 今いる関数の引数と値を表示する |
| w(where) | 呼び出し履歴を表示する(いちばん下が今の場所) |
| u(up)/ d(down) | 呼び出し履歴の 1 つ上(呼び出し元)/ 1 つ下へ移る |
| b(break) | ブレークポイントを置く。引数なしなら一覧を表示する |
| cl(clear)番号 | ブレークポイントを消す |
| q(quit) | デバッガーを終える(実行中のプログラムも止まる) |
| h(help) | 命令の一覧。h n で n の説明 |
何も入力せずに Enter を押すと、直前の命令をもう一度実行します。n を続けて打つ代わりに Enter を押していけば、1 行ずつ進められます。
n と s の違い:関数の中に入るかどうか
8 行目で止まっている状態から、n と s を打ち比べます。まず ll で関数全体を見てから n を打ちました。
> c:\work\calc.py(8)total()
-> result += price + tax(price) * qty
(Pdb) ll
4 def total(items):
5 result = 0
6 for name, price, qty in items:
7 breakpoint()
8 -> result += price + tax(price) * qty
9 return result
(Pdb) n
> c:\work\calc.py(6)total()
-> for name, price, qty in items:
n では tax() の呼び出しも含めて 8 行目が実行され、次は total 関数の 6 行目(for の行)で止まりました。次に、同じ 8 行目から s を打ちます。
> c:\work\calc.py(8)total()
-> result += price + tax(price) * qty
(Pdb) s
--Call--
> c:\work\calc.py(1)tax()
-> def tax(price):
(Pdb) s
> c:\work\calc.py(2)tax()
-> return price * 10 // 100
(Pdb) s
--Return--
> c:\work\calc.py(2)tax()->20
-> return price * 10 // 100
(Pdb) s
> c:\work\calc.py(6)total()
-> for name, price, qty in items:
(Pdb) p result
260
s では tax 関数の中に入り、--Call--(関数に入った)→ 2 行目 → --Return--(戻る直前。->20 が戻り値)の順に止まりました。tax() のあとの * qty や += は s で 1 歩ずつ止まらず、次は 6 行目です。

使い分けは、怪しくない関数は n で飛ばし、中を見たい関数だけ s で入るのが基本です。s で入ったけれど中は見なくてよかったときは、r で関数の終わりまで進めます。sum() のような組み込み関数は Python で書かれていないため、s でも中には入りません(avg.py の sum(scores) の行で s を打つと、そのまま次の行で止まりました)。
ブレークポイントを置く・消す(b・cl・c)
ソースに breakpoint() を書かなくても、pdb の中から b で止める場所を足せます。b 行番号 か b 関数名 で指定し、c でそこまで進めます。
> c:\work\calc.py(8)total()
-> result += price + tax(price) * qty
(Pdb) b tax
Breakpoint 1 at c:\work\calc.py:1
(Pdb) c
> c:\work\calc.py(2)tax()
-> return price * 10 // 100
(Pdb) a
price = 200
(Pdb) r
--Return--
> c:\work\calc.py(2)tax()->20
-> return price * 10 // 100
b tax は tax 関数の最初の行(1 行目)に置かれ、実際には中身の 2 行目で止まりました。a で引数を、r で戻り値(->20)を確かめています。
ブレークポイントを消すときは cl 番号 とします。番号を付けずに cl だけを打つと「Clear all breaks?」と確認が出るので、全部消すなら y と答えます。
py -m pdb で最初から動かす
ソースを書き換えたくないときは、pdb の下でスクリプトを起動します。例として、成績の平均を表示する avg.py を使います。鈴木さんの点数が空のため、途中でエラーになります。
def average(scores):
total = sum(scores)
n = len(scores)
return total / n
def report(data):
for name, scores in data.items():
avg = average(scores)
print(f"{name}: {avg:.1f}")
data = {"佐藤": [80, 90, 70], "鈴木": [], "田中": [60, 75]}
report(data)
ふつうに実行すると、佐藤: 80.0 を表示したあと ZeroDivisionError: division by zero(0 で割った)で止まります。pdb の下で起動します。
py -m pdb avg.py
最初の行で止まるので、「n が 0 のときだけ止まる」条件付きブレークポイントを 4 行目に置き(b 行番号, 条件)、c で進めます。
> c:\work\avg.py(1)<module>()
-> def average(scores):
(Pdb) b 4, n == 0
Breakpoint 1 at c:\work\avg.py:4
(Pdb) b
Num Type Disp Enb Where
1 breakpoint keep yes at c:\work\avg.py:4
stop only if n == 0
(Pdb) c
佐藤: 80.0
> c:\work\avg.py(4)average()
-> return total / n
(Pdb) p n
0
佐藤さんの回(n が 3)では止まらず、n が 0 になった回だけで止まりました。ループの何百回目かでだけ起きる不具合も、条件を付ければ一発でその回に止められます。<module> は「どの関数にも入っていない、ファイルのいちばん外側」という意味です。
呼び出し履歴をたどる(w・u・d)
average 関数の中では、どの人の点数なのかが分かりません。w で呼び出し履歴を見て、u で呼び出し元の report 関数に移ると、そこの変数が見られます。
(Pdb) w
c:\...\python312\lib\bdb.py(606)run()
-> exec(cmd, globals, locals)
<string>(1)<module>()
c:\work\avg.py(12)<module>()
-> report(data)
c:\work\avg.py(8)report()
-> avg = average(scores)
> c:\work\avg.py(4)average()
-> return total / n
(Pdb) u
> c:\work\avg.py(8)report()
-> avg = average(scores)
(Pdb) p name, scores
('鈴木', [])
(Pdb) d
> c:\work\avg.py(4)average()
-> return total / n
w の表示はトレースバックと同じく下が新しい順で、行頭の > が今見ている場所です。上の 2 つ(bdb.py と <string>)は pdb 自身の部分なので読み飛ばして構いません。トレースバックの読み方は「Pythonの例外処理入門」で解説しています。
エラーで止まったところから調べる(事後デバッグ)
エラーの原因を調べるだけなら、ブレークポイントを置かなくても構いません。py -m pdb で起動したプログラムが例外で止まると、pdb は自動でエラーが起きた瞬間の状態に入ります。これを事後デバッグ(post-mortem)と呼びます。最初の行で c を打つだけです。
> c:\work\avg.py(1)<module>()
-> def average(scores):
(Pdb) c
佐藤: 80.0
Traceback (most recent call last):
(途中省略)
File "C:\work\avg.py", line 4, in average
return total / n
~~~~~~^~~
ZeroDivisionError: division by zero
Uncaught exception. Entering post mortem debugging
Running 'cont' or 'step' will restart the program
> c:\work\avg.py(4)average()
-> return total / n
(Pdb) p n
0
(Pdb) q
Post mortem debugger finished. The C:\work\avg.py will be restarted
> c:\work\avg.py(1)<module>()
-> def average(scores):
(Pdb) q
エラーが起きた 4 行目で止まり、n が 0 だったことが分かりました。注意点は、事後デバッグで q を打つと、終わらずにプログラムが最初から始め直されることです(「will be restarted」と出ます)。最初の行に戻ったところで、もう一度 q を打つと終わります。
最初の行で毎回 c を打つのが面倒なら、-c continue を付けると、起動してすぐ実行を続け、エラーのところで止まります。
py -m pdb -c continue avg.py
対話モードで pdb.pm() を使う
pdb を付けずに実行してエラーになってから「中を見たかった」と思ったときは、-i を付けて実行すると、終わったあとに対話モード(>>>)に入れます。そこで pdb.pm() を呼ぶと、直前のエラーの場所を調べられます。
py -i avg.py
佐藤: 80.0
Traceback (most recent call last):
(途中省略)
ZeroDivisionError: division by zero
>>> import pdb; pdb.pm()
> c:\work\avg.py(4)average()
-> return total / n
(Pdb) p n, total
(0, 0)
(Pdb) u
> c:\work\avg.py(8)report()
-> avg = average(scores)
(Pdb) p name
'鈴木'
(Pdb) q
>>>
pdb.pm() の q では始め直しは起きず、対話モードに戻ります。exit() で終わります。
よくある間違い・落とし穴
変数 n を見ようとして、次の行に進んでしまう
pdb は、命令として知らない入力を Python の式として実行します。そのため変数名だけを打っても値が出ますが、n・c・s・l・p・a・b・q など、命令と同じ名前の変数ではそうなりません。avg.py の 4 行目で止まっているときに、変数 n を見るつもりで n と打つと、こうなります。
> c:\work\avg.py(4)average()
-> return total / n
(Pdb) p n
0
(Pdb) !n
0
(Pdb) n
ZeroDivisionError: division by zero
> c:\work\avg.py(4)average()
-> return total / n
最後の n は next 命令として扱われ、4 行目が実行されて例外が起きました。命令と同じ名前の変数は、p n のように p を付けるか、!n のように先頭に ! を付けます。! は「この行は命令ではなく Python の文」という印で、!n = 1 のように変数を書き換えることもできます。迷ったら、いつも p を付ける習慣にすると安全です。
最初の行ではまだ変数がない
py -m pdb avg.py の直後は 1 行目を実行する前なので、ファイルの下のほうで作る変数はまだありません。
> c:\work\avg.py(1)<module>()
-> def average(scores):
(Pdb) pp data
*** NameError: name 'data' is not defined
pdb の中で起きたエラーは *** 付きで表示されるだけで、デバッグは続けられます。b で止めたい場所を置き、c で進めてから調べます。
q で終えると BdbQuit のトレースバックが出る
breakpoint() で止めたあとに q で終えると、次のような表示が出ます(Python 本体の場所は省略)。
(Pdb) q
Traceback (most recent call last):
File "C:\work\calc.py", line 12, in <module>
print(total(items))
^^^^^^^^^^^^
(途中省略)
bdb.BdbQuit
q は「プログラムごと中断する」命令なので、BdbQuit という例外で止まった扱いになります。エラーに見えますが、自分で止めた結果なので心配はいりません。最後まで動かしたいときは、q ではなく c で続けます。breakpoint() がループの中にあるときは、c のたびに次の回でまた止まります。
breakpoint() を消し忘れて本番で止まる
breakpoint() はコードの一部なので、消し忘れるとそのまま本番でも止まります。人が見ていないターミナルで動いていれば入力待ちのまま進まなくなり、入力のない環境(標準入力が空)では、すぐに BdbQuit で終わりました。calc.py の標準入力を空にして(Git Bash で py calc.py < /dev/null)実行した結果です。
> c:\work\calc.py(8)total()
-> result += price + tax(price) * qty
(Pdb)
Traceback (most recent call last):
(途中省略)
bdb.BdbQuit
どちらも、本番で起きると困ります。コミットの前に breakpoint( と pdb で検索する、Git のフック(「Gitフック」参照)で検出する、といった対策をしておきましょう。
PYTHONBREAKPOINT=0 で breakpoint() を無効にする
環境変数 PYTHONBREAKPOINT を 0 にすると、breakpoint() は何もせずに戻ります(公式ドキュメントの sys.breakpointhook() の説明)。ソースを書き換えずに、止まらずに最後まで動かしたいときに使えます。PowerShell では次の 2 行です。
$env:PYTHONBREAKPOINT = "0"
py calc.py
止まらずに 404 とだけ表示されました。この設定はその PowerShell の画面を閉じるまで続くので、元に戻すには Remove-Item Env:PYTHONBREAKPOINT を実行します。Git Bash なら、その 1 回だけ有効にする書き方ができます。
PYTHONBREAKPOINT=0 py calc.py
ただし、これは消し忘れの「保険」です。本番の環境に設定していても、py -E や py -I のように PYTHON で始まる環境変数を無視する起動のしかたでは効きません。breakpoint() は消してからコミットするのが基本です。なお、import pdb; pdb.set_trace() と直接書いた場合は、この環境変数では止められません(PYTHONBREAKPOINT が働くのは breakpoint() の経由だけです)。
VS Code のデバッガーとの関係
VS Code に Python 拡張機能を入れると、行番号の左をクリックしてブレークポイントを置き、変数の一覧を画面で見ながら同じことができます。キー操作は pdb の命令とおおむね対応していて、F10(Step Over)が n、F11(Step Into)が s、Shift+F11(Step Out)が r、F5(Continue)が c に当たります。キーの一覧は「VS Codeの便利なショートカットキー」にまとめています。
なお、この記事では VS Code のデバッグ画面は実機で確認していません。画面の操作は VS Code の公式ドキュメントを確認してください。サーバー上や SSH 先などエディターが使えない場所では、どこでも動く pdb が役に立ちます。
よくある質問
breakpoint() と pdb.set_trace() はどちらを使えばいい?
Python 3.7 以降なら breakpoint() がおすすめです。import が要らず、PYTHONBREAKPOINT=0 で無効にでき、環境変数で別のデバッガーに切り替えることもできます。止まり方は同じです。
ループの中の breakpoint() で毎回止まって進まない
c を打つと、次の回の breakpoint() でまた止まります。calc.py でも、1 回目の c のあと、ペンの回でもう一度 8 行目に止まりました。特定の回だけ止めたいなら、breakpoint() を if name == "ペン": の中に入れるか、breakpoint() を使わず b 行番号, 条件 の条件付きブレークポイントを使います。
pdb の中で変数の値を変えられる?
できます。!n = 1 のように、先頭に ! を付けて代入文を書きます。「この値だったら正しく動くか」を、ソースを直す前に試せます。
テストとどう使い分ける?
pdb は「今起きている不具合の原因を探す」道具で、テストは「直したものが二度と壊れないことを確かめ続ける」仕組みです。pdb で原因が分かったら、その条件(今回なら点数が空のリスト)をテストに書いておくと再発を防げます。書き方は「Pythonのテスト入門」を参照してください。
まとめ
- 止めたい場所に breakpoint() を書くか、
py -m pdb ファイル名で起動する - -> の行は「次に実行する行」。p で値を見て、n(関数に入らない)と s(関数に入る)で進める
- エラーの原因調べは、py -m pdb の事後デバッグか pdb.pm() で、止まった瞬間の変数を見る
- 命令と同じ名前の変数は p n や !n で表示する。breakpoint() はコミット前に消す
関連する記事・ツール
- Pythonの例外処理入門|try・except・finally・raiseの使い方
- Pythonのloggingの使い方|printから卒業するログ出力の基本と設定例
- Pythonのテスト入門|unittestとpytestの書き方・実行方法を実例で比較
- Pythonのunittest.mock入門|patchで外部APIや時刻を差し替える
- VS Codeの便利なショートカットキー(Windows)|行の移動・検索置換・ターミナル