Insert a built-in breakpoint
Pause execution and enter the configured debugger.
pythonANYbreakpointpdbinteractive
python
breakpoint()Notes
Uses Python's built-in breakpoint hook. By default this opens pdb in interactive runs.
Python Debugging Cheat Sheet
Core Python debugging commands, traceback inspection, runtime introspection, and practical troubleshooting workflows.
Export
Copy the compact sheet, download it, or print it.
Download
`D` dense toggle · `C` copy all
Breakpoints and pdb
Interactive debugging with built-in breakpoints and pdb.
Drop into pdb at a specific line
Classic explicit breakpoint using pdb.
pythonANYpdbset-tracebreakpoint
python
import pdb; pdb.set_trace()Notes
Useful when you want an explicit dependency-free breakpoint in scripts and older codebases.
bash
python -m pdb app.pyNotes
Starts the debugger before the first line of the script and lets you step through execution.
Run a script with pdb and arguments
Pass normal program arguments when starting under pdb.
bashANYpdbargumentscli
bash
python -m pdb app.py --env dev --port 8000text
nNotes
In pdb, `n` runs the current line and stops at the next line in the same frame.
text
stext
ctext
untiltext
ltext
p variable_nametext
pp complex_objecttext
wMove up and down stack frames
Navigate the traceback to inspect caller frames.
textANYpdbframestraceback
text
u
dSet a breakpoint in pdb
Break on a file and line number from within the debugger.
textANYpdbbreakpoints
text
b app.py:42Tracebacks and Exceptions
Capture and inspect failures quickly.
Print the current exception traceback
Dump the active exception traceback in an except block.
pythonANYtracebackexceptionsdiagnostics
python
import traceback
try:
risky_call()
except Exception:
traceback.print_exc()python
import traceback
try:
risky_call()
except Exception:
error_text = traceback.format_exc()Get exception info tuple
Access exception type, value, and traceback explicitly.
pythonANYexceptionssystraceback
python
import sys
try:
risky_call()
except Exception:
exc_type, exc_value, exc_tb = sys.exc_info()Preserve context with raise from
Chain exceptions to keep original failure context.
pythonANYexceptionschainingdebugging
python
try:
parse_config()
except ValueError as exc:
raise RuntimeError("Invalid configuration") from excEnable faulthandler
Print Python tracebacks on fatal errors like segfaults.
pythonANYfaulthandlercrashsegfault
python
import faulthandler
faulthandler.enable()Enable faulthandler from CLI
Turn on fatal error tracebacks without code changes.
bashANYfaulthandlercli
bash
python -X faulthandler app.pybash
python -Wd app.pyRun in Python development mode
Enable extra runtime checks and debug-friendly behavior.
bashANYdev-moderuntimediagnostics
bash
python -X dev app.pyRuntime Inspection
Inspect objects, frames, environment, and imports.
Inspect object type and attributes
Quickly see what an object is and what it exposes.
pythonANYinspectionobjects
python
print(type(obj))
print(dir(obj))python
print(vars(obj))python
from pprint import pprint
pprint(payload)python
import inspect
print(inspect.signature(func))python
import inspect
print(inspect.getsource(func))python
import sys
for path in sys.path:
print(path)Show the file backing an imported module
Confirm which module file was actually imported.
pythonANYimportsmodule-resolution
python
import package_name
print(package_name.__file__)Inspect environment variables
Print environment values affecting program behavior.
pythonANYenvironmentconfiguration
python
import os
print(os.environ.get("APP_ENV"))Logging and Diagnostics
Use structured, actionable logs for faster debugging.
python
import logging
logging.basicConfig(level=logging.DEBUG)
logging.debug("Starting debug run")python
import logging
logging.basicConfig(
level=logging.INFO,
format='%(asctime)s %(levelname)s %(name)s %(message)s',
)Log an exception with traceback
Emit the stack trace automatically in an except block.
pythonANYloggingexceptionstraceback
python
import logging
logger = logging.getLogger(__name__)
try:
risky_call()
except Exception:
logger.exception("Request processing failed")Attach request or job context to logs
Add contextual identifiers that make debugging easier.
pythonANYloggingcontext
python
import logging
base_logger = logging.getLogger(__name__)
logger = logging.LoggerAdapter(base_logger, {"request_id": request_id})
logger.info("Processing request")python
import time
start = time.perf_counter()
result = expensive_call()
elapsed = time.perf_counter() - start
print(f"Elapsed: {elapsed:.4f}s")Benchmark small snippets with timeit
Measure a small expression from the command line.
bashANYtimeitbenchmark
bash
python -m timeit "sum(range(1000))"pytest and unittest Debugging
Debug tests and isolate flaky or failing behavior.
bash
pytest -xbash
pytest --pdbbash
pytest -sbash
pytest tests/test_api.py::test_create_userbash
pytest --lfShow local variables in tracebacks
Reveal local state in failing assertions and exceptions.
bashANYpytesttracebackslocals
bash
pytest -vv --showlocalsbash
python -m unittest -v tests.test_serviceProfiling and Memory
Distinguish slow code from broken code and inspect resource usage.
bash
python -m cProfile app.pybash
python -m cProfile -s tottime app.pypython
import cProfile
import pstats
profiler = cProfile.Profile()
profiler.enable()
expensive_call()
profiler.disable()
pstats.Stats(profiler).sort_stats('tottime').print_stats(20)Track memory allocations with tracemalloc
Capture memory allocation snapshots.
pythonANYmemorytracemalloc
python
import tracemalloc
tracemalloc.start()
# run code
snapshot = tracemalloc.take_snapshot()
for stat in snapshot.statistics('lineno')[:10]:
print(stat)Inspect process memory and CPU with psutil
Check runtime resource usage from inside the process.
pythonANYpsutilmemorycpu
python
import os
import psutil
process = psutil.Process(os.getpid())
print(process.memory_info())
print(process.cpu_percent(interval=1.0))Notes
Requires the third-party `psutil` package, but it is extremely useful for production debugging and local diagnostics.
Async, Web, and Production Troubleshooting
Common debugging patterns for servers, workers, and async code.
bash
PYTHONASYNCIODEBUG=1 python app.pypython
import asyncio
async def main():
...
asyncio.run(main(), debug=True)Start a simple HTTP server for quick testing
Serve files locally to reproduce client behavior.
bashANYhttp-serverrepro
bash
python -m http.server 8000bash
python -X importtime app.pyDump stack traces for all threads
Useful when an app appears hung or deadlocked.
pythonANYthreadssignalshung-process
python
import faulthandler
import signal
faulthandler.register(signal.SIGUSR1)Notes
After registering a signal, send `SIGUSR1` to the process to dump thread stack traces.
More in Python Debugging
Python Profiling and Troubleshooting Cheat Sheet
Profile Python programs, inspect memory and imports, and diagnose slow or stuck processes.
Python Test Debugging Cheat Sheet
pytest and unittest debugging patterns for isolating failures, flaky tests, fixtures, and CI-only issues.
Python Logging and Tracing Cheat Sheet
Reference for Python logging, stack traces, warning visibility, trace hooks, and instrumentation patterns.
Python pdb and Breakpoint Cheat Sheet
Focused reference for pdb commands, breakpoints, stepping, stack frames, and conditional debugging.