# Stdlib — already there
python -c "import pdb; print(pdb.__doc__[:60])"

# Optional: IPython-flavored prompt with tab completion + syntax colors
pip install ipdb

# Optional: drop-in replacement with sticky mode + better tracebacks
pip install pdbpp

# Optional: curses-based full-screen TUI debugger
pip install pudb

The Python Debugger Pdb
=======================

To use the debugger in its simplest form:

# Launch a script under pdb from the start
python -m pdb script.py [ARGS...]

# Run a module under pdb
python -m pdb -m mypackage.cli [ARGS...]

# Continue running after an uncaught exception (post-mortem mode)
python -m pdb -c continue script.py

# app.py
def compute(rows: list[dict]) -> int:
    total = 0
    for row in rows:
        breakpoint()          # 3.7+ — pauses here
        total += row["value"]
    return total

compute([{"value": 10}, {"value": 20}])

python app.py

> /home/alice/app.py(5)compute()
-> total += row["value"]
(Pdb) p row
{'value': 10}
(Pdb) p total
0
(Pdb) c
> /home/alice/app.py(5)compute()
-> total += row["value"]
(Pdb) c

# Use ipdb instead of stock pdb
PYTHONBREAKPOINT=ipdb.set_trace python app.py

# Disable all breakpoint() calls (turns them into no-ops)
PYTHONBREAKPOINT=0 python app.py

# Use VS Code's debugpy listener
PYTHONBREAKPOINT=debugpy.breakpoint python app.py

(Pdb) b 42                            # break at line 42 of the current file
(Pdb) b app.py:42                     # break at line 42 of app.py
(Pdb) b compute                       # break at the start of compute()
(Pdb) b compute, total > 100          # break in compute() only when total > 100
(Pdb) b                                # list all breakpoints
Num Type         Disp Enb   Where
1   breakpoint   keep yes   at /home/alice/app.py:42
(Pdb) condition 1 total > 100         # make existing bp 1 conditional
(Pdb) ignore 1 5                      # skip the next 5 hits of bp 1
(Pdb) cl 1                            # clear bp 1
(Pdb) cl                              # clear ALL breakpoints (after confirm)

(Pdb) p row                       # print
{'value': 10}
(Pdb) pp some_big_dict            # pretty-print
{'a': 1,
 'b': [1, 2, 3, 4, 5],
 ...}
(Pdb) whatis row                  # what type is it?
<class 'dict'>
(Pdb) row["value"] = 999          # mutate a local
(Pdb) p row
{'value': 999}
(Pdb) ! total = 0                 # the ! prefix runs any Python statement
(Pdb) interact                    # drop into a full REPL with this scope
*pdb interact start*
>>> [r["value"] for r in rows]
[10, 20]
>>> exit()
*exit from pdb interact*

(Pdb) w
  /home/alice/run.py(12)<module>()
-> compute(rows)
  /home/alice/app.py(5)compute()
-> total += row["value"]
> /home/alice/app.py(5)compute()
-> total += row["value"]
(Pdb) u
> /home/alice/run.py(12)<module>()
-> compute(rows)
(Pdb) p rows
[{'value': 10}, {'value': 20}]
(Pdb) d
> /home/alice/app.py(5)compute()
-> total += row["value"]

# crash.py
def divide(a, b):
    return a / b

def main():
    pairs = [(10, 2), (10, 0), (10, 5)]
    return [divide(a, b) for a, b in pairs]

main()

# Option A: re-run the script under pdb and continue until it crashes
python -m pdb -c continue crash.py

Traceback (most recent call last):
  File "/home/alice/crash.py", line 6, in main
    return [divide(a, b) for a, b in pairs]
  File "/home/alice/crash.py", line 2, in divide
    return a / b
ZeroDivisionError: division by zero
Uncaught exception. Entering post mortem debugging
Running 'cont' or 'step' will restart the program
> /home/alice/crash.py(2)divide()
-> return a / b
(Pdb) a            # show frame arguments
a = 10
b = 0
(Pdb) w
  /home/alice/crash.py(8)<module>()
-> main()
  /home/alice/crash.py(6)main()
-> return [divide(a, b) for a, b in pairs]
> /home/alice/crash.py(2)divide()
-> return a / b

# main.py
import os
import pdb
import sys
import traceback

def main():
    raise ValueError("simulated failure")

if __name__ == "__main__":
    try:
        main()
    except Exception:
        if os.environ.get("DEBUG_PM"):
            traceback.print_exc()
            pdb.post_mortem()
        else:
            raise

DEBUG_PM=1 python main.py

Traceback (most recent call last):
  File "/home/alice/main.py", line 11, in <module>
    main()
  File "/home/alice/main.py", line 7, in main
    raise ValueError("simulated failure")
ValueError: simulated failure
> /home/alice/main.py(7)main()
-> raise ValueError("simulated failure")
(Pdb)

# loop.py
def process(items):
    for i, item in enumerate(items):
        result = item ** 2
        print(i, result)

process(range(1000))

python -m pdb loop.py

(Pdb) tbreak loop.py:4, i == 742
Breakpoint 1 at /home/alice/loop.py:4
(Pdb) c
0 0
1 1
...
> /home/alice/loop.py(4)process()
-> print(i, result)
(Pdb) p i, result
(742, 550564)
(Pdb) c
743 552049
...

(Pdb) display total
display total: 0
(Pdb) n
> /home/alice/app.py(5)compute()
-> total += row["value"]
display total: 0  [old: ...]
(Pdb) n
display total: 10
(Pdb) b 5
Breakpoint 1 at /home/alice/app.py:5
(Pdb) commands 1
(com) p total
(com) c
(com) end
(Pdb) c
0
10
30

# Drop into pdb on first failing assertion
pytest --pdb

# Drop into pdb at the start of every test
pytest --trace

# Show stdout/stderr live — needed so the (Pdb) prompt is visible
pytest --pdb -s

# Use ipdb instead
PYTHONBREAKPOINT=ipdb.set_trace pytest -s

# Pick one of these — they all replace stock pdb when breakpoint() fires
export PYTHONBREAKPOINT=ipdb.set_trace
export PYTHONBREAKPOINT=pudb.set_trace

# Quick check that the substitution took effect
python -c "breakpoint()"

> <string>(1)<module>()
ipdb>

# Install debugpy
pip install debugpy

# Run a script and wait for an editor to attach on port 5678
python -m debugpy --listen 0.0.0.0:5678 --wait-for-client app.py

// .vscode/launch.json — attach to the listening process above
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Attach",
      "type": "debugpy",
      "request": "attach",
      "connect": { "host": "127.0.0.1", "port": 5678 },
      "pathMappings": [
        { "localRoot": "${workspaceFolder}", "remoteRoot": "." }
      ]
    }
  ]
}

# main.py
import os, sys

# Disable breakpoint() globally unless explicitly enabled
if not os.environ.get("DEBUG_PDB"):
    sys.breakpointhook = lambda *a, **kw: None

def hot_path(data):
    breakpoint()        # only fires when DEBUG_PDB=1
    return sum(data)

print(hot_path([1, 2, 3]))

python main.py                  # no pause
DEBUG_PDB=1 python main.py      # drops into pdb at the breakpoint()

6

pytest -x --pdb -s tests/test_orders.py::test_checkout_total
# fix nothing, just observe; on failure you land at (Pdb)
# next run, repeat only the failures:
pytest --lf -x --pdb -s

________________ test_checkout_total ________________
>   assert order.total == Decimal("19.99")
E   AssertionError: assert Decimal('20.00') == Decimal('19.99')
> /home/alice/tests/test_orders.py(42)test_checkout_total()
-> assert order.total == Decimal("19.99")
(Pdb) p order.lines
[Line(sku='SKU-A', qty=2, unit=Decimal('10.00'))]
(Pdb) p order._rounding
'ROUND_HALF_EVEN'

# pipeline.py
def fetch(url): return {"status": 200, "data": "abc"}

def normalize(payload):
    payload["data"] = payload["data"].upper()
    return payload

def store(record):
    if not record["data"].islower():        # <-- want to know who broke this invariant
        breakpoint()
    db.insert(record)

store(normalize(fetch("https://api.example.com/x")))

(Pdb) p record
{'status': 200, 'data': 'ABC'}
(Pdb) w
  /home/alice/pipeline.py(13)<module>()
-> store(normalize(fetch(...)))
> /home/alice/pipeline.py(9)store()
-> breakpoint()
(Pdb) u
> /home/alice/pipeline.py(13)<module>()
-> store(normalize(fetch(...)))
(Pdb) p normalize.__code__.co_filename + ':' + str(normalize.__code__.co_firstlineno)
'/home/alice/pipeline.py:3'

pip install remote-pdb

# Inside container app.py
from remote_pdb import RemotePdb
RemotePdb("0.0.0.0", 4444).set_trace()

# From the host
nc 127.0.0.1 4444

> /app/main.py(15)handler()
-> total = compute(rows)
(Pdb)

# bootstrap.py
import pdb, sys, traceback

def excepthook(exc_type, exc, tb):
    traceback.print_exception(exc_type, exc, tb)
    if issubclass(exc_type, TypeError):
        pdb.post_mortem(tb)

sys.excepthook = excepthook

python -c "import bootstrap; '1' + 1"

Traceback (most recent call last):
  File "<string>", line 1, in <module>
TypeError: can only concatenate str (not "int") to str
> <string>(1)<module>()
(Pdb)

# tracer.py
import sys

def tracer(frame, event, arg):
    if event == "call" and frame.f_code.co_filename.endswith("app.py"):
        print(f"call -> {frame.f_code.co_name}({frame.f_locals})")
    return tracer

sys.settrace(tracer)

import app
app.compute([{"value": 10}, {"value": 20}])

python tracer.py

call -> compute({'rows': [{'value': 10}, {'value': 20}]})

# async_app.py
import asyncio

async def fetch(n):
    breakpoint()                 # pdb lands here directly
    await asyncio.sleep(0)
    return n * 2

async def main():
    results = await asyncio.gather(fetch(1), fetch(2), fetch(3))
    print(results)

asyncio.run(main())

python async_app.py

> /home/alice/async_app.py(5)fetch()
-> await asyncio.sleep(0)
(Pdb) p n
1
(Pdb) c
> /home/alice/async_app.py(5)fetch()
-> await asyncio.sleep(0)
(Pdb) c
> /home/alice/async_app.py(5)fetch()
-> await asyncio.sleep(0)
(Pdb) c
[2, 4, 6]