Most Python bugs are not hard because the code is huge. They are hard because my mental model is wrong at one specific line. I think a variable holds one value, but it holds another. I think a function returns clean data, but one branch returns None. I think async tasks run in sequence, but timing proves otherwise. I still hit these issues after years of shipping Python services, data tools, and APIs, and the fastest way I know to close that gap is ipdb.
ipdb gives me an interactive pause button directly inside running Python code. I stop at the exact line that matters, inspect live state, step through control flow, and test tiny hypotheses before changing anything. That is very different from reading logs and guessing. In 2026, with AI coding assistants generating larger chunks of code, this matters even more: generation is faster, but debugging still decides delivery speed.
If you want a practical, modern workflow, this guide will help you install ipdb, place breakpoints with intent, use the commands that actually matter, debug recursion and data processing, work with pytest and async code, and avoid mistakes that waste hours.
Why I still reach for ipdb first
When a bug is subtle, I want evidence from runtime, not assumptions. ipdb gives me evidence fast.
I treat debugging like diagnosis. A log line is like hearing one heartbeat through a wall. A debugger is like attaching sensors directly to the patient. I see the current frame, local variables, call stack, and branch behavior right where the problem happens.
Here is when I choose ipdb immediately:
- A value is wrong but I cannot tell where it changed.
- A branch runs unexpectedly in a nested condition.
- A recursive or async function behaves correctly for some inputs and fails for others.
- A generated code block from an AI assistant passes linting but fails logic checks.
- A unit test fails with unclear intermediate state.
- A data transformation pipeline silently drops or mutates records.
Here is when I do not use it first:
- A simple syntax error the interpreter already pinpoints.
- A clear exception with a direct one-line fix.
- Performance-only investigation where profiling tools are better.
- Production incidents where attaching a debugger is unsafe or disruptive.
For day-to-day development, ipdb is usually my shortest path from symptom to root cause.
Install and place your first useful breakpoint
You only need one package:
pip install ipdb
Then add a breakpoint where uncertainty starts:
import ipdb
def calculate_total(items):
subtotal = sum(item[‘price‘] * item[‘qty‘] for item in items)
ipdb.set_trace() # pause right before discount logic
discount = 0.1 if subtotal > 100 else 0.0
return subtotal * (1 – discount)
A few rules I follow:
- Break before a suspicious decision, not after it.
- Break at boundaries: function entry, before return, before external calls.
- Remove or guard breakpoints before shipping.
When execution hits ipdb.set_trace(), I enter an interactive prompt. From there, I control the program line by line.
If I am using Python 3.12+ with modern tooling, I still prefer ipdb over raw pdb because tab completion, nicer display, and shell ergonomics reduce friction. Debugging is already cognitive work; I do not want extra command friction on top.
I also use breakpoint() in many codebases and map it to ipdb via environment settings when needed. This keeps code cleaner than importing ipdb in many files:
# file: app.py
def handler(payload):
breakpoint() # resolves to configured debugger
return transform(payload)
That approach gives me two benefits:
- I can disable breakpoints globally in CI with environment configuration.
- I can switch debugger implementation without editing code in many places.
Commands I use constantly (and what each one tells me)
I do not need 40 commands. I need a small set I can use without thinking.
Short
When I use it
—
—
next n
Step through local logic
step s
Verify internals of a call
continue c
Skip known-good sections
print expr p expr
Check values quickly
quit q
End session immediately
pp expr pp expr
Read nested dict/list output
where w
Understand call path
up / down u / d
Inspect caller/callee context
args a
Validate inputs at frame start
list l
Reorient quickly in file
until unt
Skip repetitive loop iterations
return r
Exit deep function quickly
! statement !
Run quick experiments in placeMy default rhythm is:
pkey variables.nthrough suspicious lines.sonly when a called function is likely wrong.wplusuordwhen context looks inconsistent.conce confidence is restored.
That rhythm keeps sessions short and focused.
I also rely on a few command combinations that save time:
wthenutwice thenp some_var: fastest way to verify if the caller passed bad state.pp payloadthen! list(payload.keys()): fast schema triage for mixed JSON inputs.untin loops plus occasionalp i, item: useful when only one iteration is broken.rfrom deep helper functions: avoids death-by-nwhen internals are already known-good.
Breakpoint placement strategy that scales
Where I put breakpoints matters more than how many I place. Random breakpoints create noise. Strategic breakpoints isolate causality.
I think in terms of state transitions:
- Input boundary: where external data first enters Python objects.
- Transformation boundary: where values are normalized, filtered, merged, or enriched.
- Decision boundary: where control flow forks (
if,match, retries, fallback logic). - Output boundary: where values are returned, persisted, or sent to another service.
If I do not know where corruption enters, I use a binary-search strategy:
- Break near output and confirm value is wrong.
- Move halfway upstream and check again.
- Repeat until I identify the first incorrect state.
This approach is faster than stepping from the top every time.
In larger services, I often add temporary helper wrappers for targeted tracing plus breakpoints:
def dbg(label, value):
print(f‘[dbg] {label}={value!r}‘)
return value
def build_invoice(raw):
customerid = dbg(‘customeridraw‘, raw.get(‘customerid‘))
breakpoint()
…
I remove these quickly after root cause is confirmed, but during investigation they keep me honest about where assumptions fail.
Walkthrough: debugging recursion with factorial
Recursion bugs usually come from base cases, argument progression, or hidden mutation. Here is a runnable script:
import ipdb
def factorial(n):
if n <= 0:
return 1
return n * factorial(n – 1)
ipdb.set_trace()
number = 5
result = factorial(number)
print(f‘factorial({number}) = {result}‘)
At the prompt, I run commands like this:
nto executenumber = 5.p numberto verify input.nto move to the recursive call.sto step intofactorial.ato verify eachnvalue in each frame.wto see recursion depth.rto run to each return and verify multiplication order.
What I am checking:
- Base case triggers exactly once for
n <= 0. ndecreases by one each call.- No accidental non-integer input enters recursion.
A common real bug is switching base case to if n == 0 while negative inputs exist upstream. That can produce deep recursion until a recursion limit error. With ipdb, I confirm incoming n values in seconds and decide whether to validate inputs at the boundary.
I often harden this function right after debugging:
def factorial(n):
if not isinstance(n, int):
raise TypeError(‘n must be an integer‘)
if n < 0:
raise ValueError(‘n must be >= 0‘)
if n == 0:
return 1
return n * factorial(n – 1)
The debugger session tells me exactly which guard is needed, so validation becomes precise instead of defensive guesswork.
A deeper recursion scenario appears with tree traversal. Example symptoms include missing nodes, duplicate visits, or early returns. In those cases I inspect:
- Current node identity (
id(node)helps catch aliasing). - Path accumulator mutability (shared list bugs are common).
- Return values from children before aggregation.
Most recursion bugs I see in production are not algorithm mistakes. They are state-sharing mistakes.
Walkthrough: debugging a sorting workflow with real data
Sorting itself is rarely the bug. Input shape is usually the bug.
Here is a simple version first:
import ipdb
def sort_numbers(numbers):
ipdb.set_trace()
sorted_numbers = sorted(numbers, reverse=True)
return sorted_numbers
def main():
numbers = [5, 2, 8, 1, 9, 4]
sortednumbers = sortnumbers(numbers)
print(sorted_numbers)
Now imagine production input includes strings, None, or mixed numeric types from CSV ingestion:
import ipdb
def normalizeandsort(raw_values):
ipdb.set_trace()
cleaned = []
for value in raw_values:
if value is None:
continue
if isinstance(value, str):
value = value.strip()
if value == ‘‘:
continue
value = float(value)
cleaned.append(float(value))
return sorted(cleaned, reverse=True)
At the breakpoint, I inspect:
p raw_valuesnthrough each loop branchp valuebefore and after normalizationp cleanedbefore return
This catches hidden cases fast, like locale-specific strings (‘1,200‘) or unexpected booleans (True becomes 1.0).
When debugging data pipelines, I place breakpoints at three stages:
- Raw input boundary
- Post-normalization
- Pre-output
That pattern gives me a chain of custody for data. I always know where corruption enters.
I also stress-test assumptions with quick inline experiments while paused:
! float(‘1,200‘.replace(‘,‘, ‘‘))! isinstance(True, int)! sorted([3, ‘2‘])
Those tiny experiments stop me from coding fixes based on memory of behavior that may be wrong.
Walkthrough: multiply/add bug and the moment state shifts
Small arithmetic functions are useful examples because they look harmless:
import ipdb
def multiply(x, y):
result = x * y
return result
def add(x, y):
result = x + y
return result
def main():
x = 5
y = 10
result1 = multiply(x, y)
ipdb.set_trace() # pause after multiplication
result2 = add(result1, y)
print(result2)
Now imagine this silently breaks because x came from JSON as a string (‘5‘). Then multiply(‘5‘, 10) produces string repetition and add(result1, y) crashes or misbehaves depending on coercion logic elsewhere.
At the breakpoint, I check:
p x, type(x)p y, type(y)p result1, type(result1)sintoaddonly ifresult1looks suspicious
If type drift appears, I fix near the input boundary, not deep in arithmetic helpers:
def parse_int(value, name):
try:
return int(value)
except (TypeError, ValueError):
raise ValueError(f‘{name} must be an integer‘)
That is a pattern I apply often after debugger sessions: convert hidden assumptions into explicit checks.
Conditional breakpoints and loop-heavy debugging
Many real bugs appear only under specific conditions: one user record, one timestamp format, one retry cycle, one outlier row in a 50k batch. Stopping every iteration is not practical.
I use conditional breakpoints to pause only when a predicate is true. With ipdb, this can be done through the underlying debugger commands (b, condition expression) or by guarded set_trace() in code.
Example guarded breakpoint:
for row in rows:
if row.get(‘region‘) == ‘eu‘ and row.get(‘amount‘, 0) < 0:
import ipdb; ipdb.set_trace()
process(row)
This is simple, explicit, and very effective.
For retry loops, I inspect progression variables:
- current attempt number
- exception type and message
- backoff delay value
- idempotency keys or request identifiers
I have repeatedly found bugs where retry code looked fine but reused stale payload state between attempts. One conditional breakpoint around attempt > 1 exposed that instantly.
For pagination loops, I verify:
- token changes on each request
- stop conditions include both empty page and repeated token
- aggregate length grows monotonically
These checks are easy with p token, p len(items), and n around boundary conditions.
Post-mortem debugging from exceptions
Sometimes I do not know where to place a breakpoint ahead of time. In that case, post-mortem debugging is ideal: let the error happen, then inspect state at the crash site.
Typical flow:
- Reproduce the failing command.
- Drop into debugger on exception.
- Inspect local frame and call stack.
- Move up to caller frames for bad inputs.
- Patch and re-run with the same test case.
This avoids adding temporary set_trace() lines while I am still locating the fault.
I especially like post-mortem mode for tests because I can run a single failing test repeatedly and stay close to the failure point. It shortens the loop from minutes to seconds.
When I use this approach, I always capture three facts before patching:
- the exact bad value
- the first frame where the value was already bad
- why existing tests did not catch it
Without those three facts, fixes tend to be shallow.
ipdb with tests, async code, and AI-assisted workflows
Most teams now generate tests and helper functions with AI tools. That speeds writing, but generated code can carry quiet logic errors. I use ipdb to verify behavior quickly in two places: failing tests and async boundaries.
For tests with pytest, two approaches work well:
- Keep
ipdb.set_trace()in target code temporarily. - Run tests with debugger-friendly flags and break on failures.
Example target:
# pricing.py
def apply_discount(total, tier):
if tier == ‘gold‘:
return total * 0.8
if tier == ‘silver‘:
return total * 0.9
return total
# test_pricing.py
from pricing import apply_discount
def testgolddiscount():
assert apply_discount(200, ‘gold‘) == 160
When an AI-generated test fails unexpectedly, I place ipdb.settrace() in applydiscount, rerun that single test, and inspect inputs directly.
For async code, breakpoints are still useful, but context switching can hide order issues:
import asyncio
import ipdb
async def fetchuserscore(user_id):
await asyncio.sleep(0.05)
return {‘userid‘: userid, ‘score‘: 42}
async def main():
ipdb.set_trace()
result = await fetchuserscore(‘u-1001‘)
print(result)
What I verify in async sessions:
- awaited values are what I expect
- shared mutable objects are not being mutated across tasks
- timeout and cancellation logic is reached when expected
- exceptions from tasks are not swallowed
A pattern I use often:
- I create two or three concurrent tasks with deterministic fake inputs.
- I place one breakpoint before
gather()and one after it. - I inspect each task result and exception explicitly.
This quickly exposes ordering assumptions that are hidden in normal logs.
In AI-assisted workflows, I feed assistants runtime facts from ipdb, not just tracebacks. For example:
- observed type of each critical variable
- exact branch taken
- stack frame where mutation first appears
- minimal reproducible input discovered during session
Suggestions become dramatically better when the prompt contains runtime evidence instead of abstract error text.
Traditional vs modern bug-fix loop:
Typical loop
—
Edit logs, rerun, scan output, repeat
Paste error, apply suggested fix, rerun
ipdb + AI evidence loop Inspect live state, capture facts, request targeted patch
I recommend the third approach for most non-trivial bugs.
Framework-specific patterns I use
FastAPI and request handlers
For API bugs, I pause right after request parsing and again before response serialization. I inspect:
- validated schema vs raw payload
- auth-derived context fields
- dependency-injected objects (db session, config)
This catches a lot of issues where validation passes but business logic receives optional fields in unexpected shapes.
Django views and model logic
In Django, I avoid stepping deep into ORM internals unless query behavior is suspect. Instead, I inspect:
- queryset filters and generated SQL when needed
model.full_clean()assumptions- implicit timezone conversions in datetime fields
A quick breakpoint before save often reveals stale instance state or signal side effects.
Celery or background workers
Worker bugs are often data-contract bugs. I breakpoint at task entry and inspect payload contract:
- required keys present
- version field for backward compatibility
- retry metadata and idempotency keys
If payload versioning is weak, I add a strict validator after debugging so future tasks fail fast with clear errors.
Mistakes I see repeatedly and how to avoid them
ipdb is simple, but habits decide whether it helps or frustrates me.
Mistake 1: Breakpoint too late.
- Symptom: variable is already wrong when paused.
- Fix: move breakpoint earlier, near first mutation.
Mistake 2: Stepping into everything.
- Symptom: I get lost in library internals.
- Fix: use
nby default,sonly for suspicious calls.
Mistake 3: Ignoring the stack.
- Symptom: local frame looks fine but output is wrong.
- Fix: use
w, thenuanddto inspect caller state.
Mistake 4: Leaving breakpoints in committed code.
- Symptom: CI hangs or runtime pauses unexpectedly.
- Fix: search before commit (
rg ‘set_trace\(‘) and remove.
Mistake 5: Debugging production directly.
- Symptom: blocked workers or stalled request handling.
- Fix: reproduce in staging or local with captured input.
Mistake 6: Treating debugger as final fix.
- Symptom: bug returns in a different path.
- Fix: convert findings into tests and boundary validation.
Mistake 7: Overtrusting AI-generated patches.
- Symptom: patch passes one case but breaks edge cases.
- Fix: verify branch behavior in debugger before and after patch.
Mistake 8: Not recording discovered invariants.
- Symptom: same class of bug repeats across modules.
- Fix: write invariants in tests, type hints, and validation helpers.
I recommend one team convention: annotate temporary breakpoints with a short reason.
ipdb.set_trace() # investigate tier parsing from billing payload
That makes collaborative debugging cleaner.
Performance and behavior considerations
ipdb is an interactive stop-the-world tool. It is perfect for correctness debugging, but it changes timing. I keep that in mind.
What changes when I use breakpoints:
- event loops pause, which can mask race timing
- network deadlines can expire while I inspect state
- retry windows and backoff behavior become non-representative
So I use ipdb for logic and state, then validate timing with profiling or load tests.
In practical terms, this gives me a two-stage workflow:
- Correctness pass with debugger.
- Behavior pass under realistic timing without debugger.
Before/after effort ranges I see in teams:
Typical root-cause time for medium logic bug
—
~45 to 180 minutes
ipdb focused session + targeted tests ~15 to 60 minutes
These are ranges, not guarantees, but they match what I consistently observe.
I also keep a simple rule: if pausing materially changes the bug, I switch tools rather than forcing debugger-driven analysis.
Alternative approaches and when I use them instead
I use ipdb heavily, but not blindly. Different bug classes need different tools.
Use profiling tools when:
- issue is latency, CPU, memory, or lock contention
- I need aggregate behavior across many calls
- debugger pause changes performance profile
Use tracing or log correlation when:
- bug spans multiple services or queues
- request identity must be tracked across boundaries
- incident only appears under real traffic patterns
Use property-based testing when:
- bug appears for rare input combinations
- parser or transformation has large input space
- I want to encode invariants and discover edge cases automatically
Use stronger static checks when:
- failures come from type drift repeatedly
- protocol contracts are unclear
- optional fields and union types are common
Comparison table:
Best for
—
ipdb Local runtime state, branch logic, call stack truth
Historical replay and production visibility
CPU/latency hotspots
Cross-service flow and dependency timing
Edge-case discovery at scale
Preventive guardrails
My decision rule is simple:
- unknown runtime state at one location:
ipdb - system-wide timing or distributed flow: tracing/profiling
- input-space explosion: property tests
Production-safe debugging workflow
I never attach live interactive debug sessions to critical production paths. Instead, I use a safe workflow:
- Capture failing input and environment metadata.
- Reproduce locally or in staging with same versions.
- Use
ipdbto locate first bad state. - Patch with minimal scope.
- Add regression test for exact failure mode.
- Roll out gradually and monitor key metrics.
For captured metadata, I care about:
- request payload snapshot (redacted)
- feature flag state
- timezone/locale settings
- dependency versions
- worker/runtime configuration
Most reproducibility failures come from missing context, not missing debugger skill.
I also avoid logging sensitive data just to debug faster. If secrets are involved, I inspect in-memory values locally with redacted fixtures whenever possible.
Converting debugger findings into lasting quality
A debugger session is only complete when I turn insights into prevention.
After root cause, I usually do three follow-ups:
- add one narrow regression test for the exact bug
- add one boundary validation if external data caused it
- add type hints or schema constraints to prevent recurrence
Example progression:
- Discovery in
ipdb:tiermay include‘Gold ‘with trailing spaces. - Fix: normalize with
.strip().lower()at input boundary. - Guardrail: regression test with
‘ Gold ‘and mixed case. - Optional hardening: literal enum type for known tiers.
This pattern compounds over time. Each debugging session makes the system slightly harder to break.
A practical team checklist for ipdb
When I introduce ipdb workflows to a team, this checklist keeps everyone aligned:
- Reproduce first with the smallest failing input.
- Place breakpoint before the first suspicious mutation.
- Use
nby default; usesselectively. - Inspect stack early with
wif context feels wrong. - Capture facts before patching: bad value, first bad frame, missing test.
- Remove breakpoints before commit.
- Add regression test and boundary validation.
If a team follows this consistently, bug-fix quality improves fast.
Final thoughts
The real win with ipdb is not just finding one bug. It is building a repeatable feedback loop where I move from symptom to proof to fix with minimal guesswork.
If you are early in Python, start with five commands: n, s, c, p, q. Use them daily for a week and your debugging confidence will change quickly. If you are experienced, the next jump is discipline: place breakpoints intentionally, inspect stack context early, and convert every confirmed bug pattern into tests so it does not return.
In my workflow, I pair ipdb with three habits that keep projects stable as they grow:
- I validate types and schemas at data boundaries.
- I encode discovered edge cases as focused regression tests.
- I use AI assistants after gathering runtime facts, not before.
That combination gives me speed without guesswork. And in real software delivery, that is what matters most.
