Introduction

Python pdb is often used for quick variable inspection, but it can also execute multi-line logic while the program is paused. That is useful when you need to test a loop, conditional branch, or helper function without editing source files mid-debug. Once you know the block-entry pattern, pdb becomes much more practical for real debugging sessions.

Set Up a Small Debug Target

A reproducible script makes it easier to learn and verify debugger behavior.

1# debug_target.py
2import pdb
3
4orders = [
5    {"id": 101, "total": 12.5},
6    {"id": 102, "total": 8.75},
7    {"id": 103, "total": 19.2},
8]
9
10pdb.set_trace()
11print("done")

Run it:

python debug_target.py

At the prompt, test simple expressions first with p orders or p len(orders).

Execute Multi-Line Blocks with ! and Dot Terminator

Inside pdb, prefix Python statements with !. For blocks such as for and if, type indented lines and end with a single dot line.

1(Pdb) !total = 0
2(Pdb) !for row in orders:
3(Pdb) .     total += row["total"]
4(Pdb) .
5(Pdb) p total
640.45

Conditional example:

1(Pdb) !high_ids = []
2(Pdb) !for row in orders:
3(Pdb) .     if row["total"] > 10:
4(Pdb) .         high_ids.append(row["id"])
5(Pdb) .
6(Pdb) p high_ids
7[101, 103]

This is the core mechanic for multi-line statements in pdb, and it is the part most people miss when they assume the debugger only supports one-line commands.

Define Temporary Helper Functions in Session

For repeated checks, defining a temporary function can be cleaner than retyping loops.

1(Pdb) !def with_tax(value, rate=0.13):
2(Pdb) .     return round(value * (1 + rate), 2)
3(Pdb) .
4(Pdb) p [with_tax(r["total"]) for r in orders]
5[14.12, 9.89, 21.7]

Use clear temporary names so you do not confuse debug helpers with real module functions.

Use interact for Larger Exploratory Work

When prompt-based typing becomes awkward, use interact to open a full interactive interpreter in the current frame.

1(Pdb) interact
2*interactive*
3>>> totals = [row["total"] for row in orders]
4>>> sum(totals)
540.45
6>>> quit()
7*exited interactive mode*
8(Pdb)

interact is useful for exploration, but remember session edits are temporary and disappear when the process ends.

Automate Repeated Inspection with Breakpoint Commands

If the same breakpoint is hit many times, attach a command block to print state automatically.

1(Pdb) b 12
2Breakpoint 1 at debug_target.py:12
3(Pdb) commands 1
4(com) p orders
5(com) !print("sum", sum(r["total"] for r in orders))
6(com) continue
7(com) end

This can save time in loops and race condition investigations.

Use display for Variable Watch Behavior

pdb supports watched expression output with display.

(Pdb) display len(orders)
display len(orders): 3

When execution continues and returns to prompt, changed display expressions are shown automatically. This helps track evolving state without manual prints.

Workflow Tips for Faster Debugging

A practical debugging flow:

1. Stop at a breakpoint near suspected logic.
2. Use quick p checks for baseline state.
3. Run a small multi-line block to test assumptions.
4. Use helper function if a calculation repeats.
5. Continue and observe changes with display or breakpoint commands.

This keeps experiments focused and reduces source-code churn while investigating issues.

Common Pitfalls

• Forgetting ! prefix, so input is interpreted as debugger command instead of Python.
• Not ending block input with a dot line, leaving prompt waiting for continuation.
• Indentation mistakes in multi-line blocks.
• Assuming interact changes are permanent code edits.
• Creating temporary helper names that shadow important variables or functions.

Summary

• Use ! plus indented lines to run multi-line Python blocks in pdb.
• End each block with a single dot line to execute it.
• Define temporary helper functions when repeated checks are needed.
• Use interact for longer exploratory sessions in current frame context.
• Combine breakpoints, command lists, and display expressions for faster iterative debugging.