Python
PR

Pythonのデバッガーpdbの使い方|breakpoint()で止めて変数を調べる

Pythonのデバッガーpdbの使い方|breakpoint()で止めて変数を調べる
hr
記事内に商品プロモーションを含む場合があります

プログラムが思いどおりに動かないとき、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 行目です。

calc.py の 8 行目で止まっているとき、n は tax 関数の中で止まらずに次は 6 行目で止まり、s は tax 関数の 1 行目と 2 行目で止まることを示す図
図 1:n は関数の中に入らず、s は関数の中に入る

使い分けは、怪しくない関数は 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() はコミット前に消す

関連する記事・ツール

ABOUT ME
hr
hr
エンジニアとして働いている hr です。仕事や資格勉強で「こんなツールがあれば」と感じたものを、無料Webツールと解説記事にして発信しています。
記事URLをコピーしました