Python’s built-in pdb debugger lets you pause a program, inspect its current state, move through the call stack, and find where an unexpected value or exception originates. Add breakpoint() where you want execution to stop, run the program with the input that reproduces the problem, then inspect values at the (Pdb) prompt. For a visual workflow, VS Code’s Python Debugger extension offers editor breakpoints, a variables view, and reusable launch configurations.
Start with a repeatable failure
Before stepping through code, make the problem reproducible: use the same command, inputs, environment variables, and relevant data that trigger it. A debugger shows one execution, not every possible behavior. If the failure is intermittent, record the inputs and conditions that precede it so you can run the same case again.
The Python 3.14.7 documentation describes pdb as an interactive source-level debugger. It supports breakpoints, stepping, stack inspection, source listing, and evaluating Python in a selected stack frame (Python 3.14.7 pdb reference). It is part of Python’s standard library, so there is no separate debugger package to install for ordinary local use.
Use breakpoint() for the quickest investigation
Put breakpoint() on the line where the program has enough context to reveal the problem. For example:
Recommended Free Tools
#1 Best Overall
def calculate_total(items):
subtotal = sum(items)
breakpoint()
return subtotal
print(calculate_total([12, 8, 5]))Run the file as you normally do, for example with python app.py. When Python reaches the breakpoint, execution pauses and the terminal displays a (Pdb) prompt. Try this short sequence:
where
list
p items
p subtotal
n
cwhereshows the call stack and the selected frame.listdisplays nearby source lines.p expressionevaluates and prints an expression, such as a local variable or a function call.nruns the next line without stepping into a function called on that line.ccontinues execution until another breakpoint or the program ends.
Use s instead of n when you want to enter a function call and follow its execution. If a command is unfamiliar, use h for general help or help command, such as help break. The official command reference is at docs.python.org/3/library/pdb.html.
Remove temporary breakpoint() calls when the investigation is complete, or leave them only when a deliberate debugging stop is part of your development workflow. A breakpoint left in application code can interrupt normal execution when someone later runs it.
Run a script or module under pdb without editing it
For a one-off investigation, start the program under the debugger rather than changing the source:
python -m pdb path/to/script.pyTo run a module by its import name, use the module form supported by pdb’s command-line interface:
python -m pdb -m package.moduleAt the prompt, use l or list to see code, n or s to advance, p expression to inspect data, and c to continue. Starting under pdb is useful when you do not know where to insert a breakpoint or cannot edit the file. By itself, this starts an interactive session; you still need to set a breakpoint, step through execution, or wait for an exception to investigate the relevant path.
Investigate exceptions and follow the stack
When a program started with python -m pdb exits because of an unhandled exception, pdb enters post-mortem debugging. Inspect the current frame and use where to see the traceback in stack form. Then move to a caller with up or back toward the failing call with down, inspecting variables in each selected frame with p expression. This helps answer both “where did the exception occur?” and “what value or call path led here?”
If an exception has already been recorded in an interactive Python session, invoke the post-mortem debugger explicitly:
import pdb
try:
run_something()
except Exception:
pdb.post_mortem()Alternatively, pdb.pm() starts post-mortem debugging for the most recent exception. Use these when you have a traceback and want to inspect live frames instead of relying only on printed values. If the exception is caught and handled before it escapes, pdb will not automatically treat it as an unhandled program exit; put a breakpoint in the relevant handler or call pdb.post_mortem() while handling the exception.
Set useful breakpoints and inspect the right frame
Break at a line or function
At the prompt, b 42 sets a breakpoint at line 42 in the current file; b module.py:42 targets a line in a named file; and b calculate_total sets one at a function. A conditional breakpoint stops only when its condition is true, for example:
b 42, subtotal < 0Use tbreak for a temporary breakpoint that removes itself after it is hit. The pdb reference also documents listing, enabling, disabling, clearing, and associating commands with breakpoints. Those controls are useful when the failure happens only after several loop iterations or on a specific input. Consult the pdb command reference for exact command syntax and options.
Move through frames, not just lines
where prints the stack; up and down select a different frame. A variable that does not exist in the current function may be available in a caller or callee, so switch frames before concluding that the value is unavailable. After selecting a frame, inspect its state with p and source with list.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Pdb input can also execute Python statements in the selected frame. This is powerful for testing a hypothesis, but assignments and function calls can mutate the program’s state or cause side effects. For example, changing a local value may make the later execution behave differently from the original failure. Prefer read-only expressions first; if you do mutate state, note exactly what you changed before interpreting what happens next.
Choose terminal pdb or VS Code’s debugger
| Situation | Terminal pdb | VS Code Python Debugger |
|---|---|---|
| Quick local inspection | Use breakpoint() or start the script with python -m pdb; interact at the (Pdb) prompt. |
Start a Python file from the editor and use graphical breakpoint and variable controls. |
| Repeatable project setup | Commands and breakpoint locations are managed in the terminal or source. | Project-specific launch settings can be saved in .vscode/launch.json. |
| Existing or remote process | Use pdb’s documented capabilities that match the installed Python version and process context. | The extension guide documents attach configurations and remote debugging; connection and source setup are required. |
| How state is viewed | Commands show frames, source, and evaluated expressions in the terminal. | The editor provides visual state inspection, breakpoints, and a debug console. |
VS Code’s Python Debugger extension uses debugpy for supported Python debugging workflows. Install the extension and select the Python environment for your project. For a basic script, choose the Python File run/debug configuration in the Run and Debug view. Project-specific configurations are stored in .vscode/launch.json; the configuration can specify a program, arguments, interpreter, terminal, or an attach request. Microsoft’s guide covers launch, attach, and remote workflows: Python debugging in VS Code.
Choose the terminal when you want a direct, low-setup inspection or post-mortem session. Choose VS Code when seeing breakpoints and values alongside source code, or reusing a project launch configuration, makes the investigation easier to manage. Attaching to a running process and remote debugging need extra configuration; do not expose a debug port publicly as a casual default. The official documentation describes workflow differences, not a benchmark showing that one debugger is universally faster or better.
Check the Python version before relying on newer behavior
Version matters for some pdb features. These notes reflect the Python 3.14.7 reference consulted on September 29, 2026; check the documentation for your installed interpreter before using a version-specific option.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →Scan for outdated or missing drivers - takes under a minuteDriver Scan →breakpoint()has been available since Python 3.7 and is the convenient built-in alternative to callingpdb.set_trace().- In Python 3.13,
pdb.set_trace()enters the debugger immediately rather than stopping on the next line. Python 3.13 also incorporates the PEP 667 behavior documented for debugger assignments: assignments made through pdb immediately affect the active scope. - Python 3.14 adds attaching to a process by PID with
-por--pid, and the asynchronouspdb.set_trace_async()entry point.
Do not assume an option documented for Python 3.14 exists in an older runtime. The versioned details are in the Python 3.14.7 pdb reference and the Python 3.14.7 debugging and profiling documentation.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshooting common pdb problems
The program never stops at breakpoint()
- Confirm the execution reaches that line. A different branch, early return, or exception before it can bypass the breakpoint.
- Check that you are running the file and Python environment you think you are. If uncertain, run the explicit script path or use
python -m pdb path/to/script.py. - If the application or environment customizes breakpoint behavior, consult the Python documentation for
breakpoint()andPYTHONBREAKPOINT; do not assume a breakpoint call always starts pdb in every customized runtime.
A name is missing or has an unexpected value
Use where to identify the current frame, then try up or down. The variable may belong to a different scope or may not yet have been assigned on this path. Check the selected frame’s source with list and inspect the value with p name.
A breakpoint condition fails or stops too often
Verify the condition is a valid expression in the frame where the breakpoint runs and that it uses the actual variable names and types. For a loop, a temporary breakpoint can limit the stop to one occurrence; a conditional breakpoint can narrow it to the input or state that matters.
Stepping appears to skip code
n runs a line without entering a called function. Use s to step into the call. Conversely, if stepping into library code makes the session noisy, use n or set a breakpoint at the application code you want to inspect.
Free tools Windows power users keep installed
One-click scans. No signup required.
VS Code launches the wrong code or environment
Confirm the selected interpreter, working directory, program path, and command-line arguments in the active configuration. If the project uses a non-default launch setup, inspect .vscode/launch.json and the configuration selected in Run and Debug. For attach or remote sessions, verify connection settings and that the source visible in the editor corresponds to the running process.
When browser screenshots are part of debugging
If the bug is visible only in a rendered page, a screenshot can preserve the appearance at a particular point in your investigation, but it does not replace pdb’s inspection of Python variables and stack frames. For repeatable screenshot capture from code, ScreenshotNeo is a website screenshot API and MCP server for developers. A GET request can return PNG, JPEG, WebP, or PDF; its clean-shot options accept cookie banners and remove more than 60 known consent platforms, newsletter popups, and chat widgets before capture, with each step independently configurable. Bot checks/CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers identify the page verdict and billing status.
Or skip the browser setup
Make one request with a URL to capture a page; see the ScreenshotNeo API documentation for supported parameters and formats. For example, this Python snippet writes the returned image bytes to a file:
import requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)It removes cookie banners, popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server gives AI agents tools to take screenshots, get page information, and capture PDFs. The Free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000.
The Tool Desk
Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Sign up for free ScreenshotNeo access.
FAQ
Can pdb debug code while it is running?
Yes. Insert breakpoint() in the code path or use a supported process-attachment workflow. PID attachment is documented as a Python 3.14 feature.
Does pdb require installing a package?
No for standard local use: pdb is part of Python’s standard library. VS Code’s editor-based workflow uses the Python Debugger extension.
Can I use pdb with asynchronous code?
Python 3.14 documents pdb.set_trace_async(). Check the reference for the exact behavior and availability in your interpreter version.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
