Python Debugging with PDB — Core Concepts

Why PDB remains valuable

Even with IDE debuggers, pdb is still essential because it works everywhere: local terminal, Docker containers, CI reproductions, and remote servers with shell access.

Starting a session

Two common entry points:

1. Add breakpoint() in code.
2. Run script under debugger:
   • python -m pdb app.py

You can also post-mortem debug after an exception with:

import pdb
pdb.pm()

Commands you use daily

• n (next): run next line in current function
• s (step): go inside called function
• c (continue): run until next breakpoint
• l (list): show nearby source lines
• p expr: print expression value
• pp expr: pretty-print complex values
• w: show call stack
• u / d: move up/down stack frames
• q: quit debugger

Effective debugging workflow

1. Reproduce the issue reliably.
2. Place breakpoint near suspicious boundary.
3. Inspect inputs and assumptions.
4. Follow control flow across function calls.
5. Confirm root cause before editing code.

Avoid coding while still guessing. Root-cause confidence saves time.

Conditional breakpoints

Stop only when a condition matches:

breakpoint()  # then in pdb: condition <bpnum> order_id == 9021

Useful for loops with thousands of iterations where only one case fails.

Common misconception

“Print debugging is always enough.” Print statements are fine for quick checks, but they are weak when bugs depend on context, stack state, or branch-specific mutation.

PDB gives full context at the exact failure moment.

Team habits that improve debugging speed

• keep functions small and side effects explicit
• add structured logs for key transitions
• write failing test before fix when possible
• capture reproduction inputs in bug tickets

Related reading: Python Logging Best Practices and Python Mocking and Monkeypatching.

The one thing to remember: debugging gets dramatically faster when you inspect live state instead of inferring it from guesses.

Capturing debugging notes effectively

During difficult incidents, write short notes while stepping through pdb: expected value, observed value, and the frame where divergence began. These notes accelerate handoffs and make post-incident learning reusable.

Combine debugger and logs

Use logs to narrow the time window, then pdb to inspect precise runtime state. Teams that combine both tools resolve edge-case bugs faster than teams relying on one method only.

Adoption playbook

A practical way to roll out debugging with pdb is to start with one critical workflow, set a measurable success signal, and review results after two weeks. Keep the first rollout intentionally small so the team learns the tool and failure modes without creating delivery risk. After the pilot is stable, document the standards in your engineering handbook and automate checks in CI. Small, repeated improvements usually beat dramatic one-time migrations.