A Python debugger pauses a running program so you can inspect its current state, trace execution, and find where behavior diverges from what you expect. For a quick terminal session, use Python’s built-in pdb; for a graphical workflow, use the Python Debugger in VS Code or PyCharm. The basic loop is the same: choose a stopping point, start or attach the debugger, inspect values and the call stack, step through code, then continue or stop.
What a Python debugger does
A debugger lets you examine a program while it is running. At a breakpoint or exception, execution pauses in a particular frame: a function’s active context, including its local variables. You can inspect expressions, move through statements, enter called functions, and examine how the program reached that point.
This is different from adding temporary print statements: you can choose when to pause and inspect multiple values without editing the program to add more output. Debuggers do not automatically identify the cause of a bug; they give you a controlled way to test hypotheses about the program’s state and execution.
Choose a debugger for your workflow
| Situation | Starting point | Why it fits |
|---|---|---|
| Small script, terminal work, or exception investigation | pdb |
It is included in Python’s standard library and supports stepping, expression evaluation, stack inspection, and post-mortem debugging. |
| Your project is already open in VS Code | Python Debugger extension | It offers a quick current-file workflow and configurable launch and attach sessions. |
| Your project is already open in PyCharm | PyCharm Debug mode | It provides an IDE debugging workflow with breakpoints and variable inspection. Check the debugger mode and documented support for your environment. |
| You need to inspect an existing or remote process | Compare each debugger’s attach and remote workflow | VS Code documents process attachment and remote debugging. PyCharm documents DAP attachment, while some scenarios are not covered by its default debugpy debugger. |
Before choosing for a specialized setup, check the Python version and interpreter location, whether you need to launch or attach, and support for remote targets, WSL, subprocesses, and your framework. A debugger that works for a local script may not cover every deployment or framework workflow.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
#1 Best Overall
Use Python’s built-in pdb
pdb is Python’s interactive source debugger. With the default breakpoint configuration, adding breakpoint() pauses execution at that line and opens the debugger in the terminal.
Pause at a chosen line
- Add
breakpoint()where you want the program to stop. - Run the script normally, for example
python path/to/script.py. - At the
(Pdb)prompt, inspect the frame, step through the relevant code, and continue when ready.
def total_with_tax(price, rate):
subtotal = price
breakpoint()
return subtotal * (1 + rate)
print(total_with_tax(20, 0.08))Useful commands at the (Pdb) prompt include:
| Command | What it does |
|---|---|
p expression |
Evaluates and prints an expression in the current frame, such as p price. |
where or w |
Shows the current stack, helping you see how execution reached this frame. |
step |
Runs the next statement and enters a called function when execution reaches it. |
next |
Runs the next statement without stepping into a called function. |
continue |
Resumes execution until another breakpoint or stop. |
To start a script under debugger control from the beginning, run python -m pdb path/to/script.py. The debugger also enters post-mortem mode if the script exits abnormally. To inspect the last exception from an available interactive session, Python documents pdb.pm().
Python 3.14 process attachment
Python 3.14 added process attachment through python -m pdb -p PID (also written --pid). This is version-specific; do not expect it in older Python releases. The Python 3.14.8 pdb reference notes that a process blocked in a system call or waiting for I/O may not be attachable until it executes another bytecode instruction or receives a signal. That limitation matters when an attachment appears to wait rather than stop immediately.
Debug Python in VS Code
VS Code’s Python Debugger supports a quick run of the open file as well as repeatable project configurations. The selected workspace interpreter is used by default; configurations can specify another interpreter.
Free tools Windows power users keep installed
One-click scans. No signup required.
Debug the open file
- Open the Python file you want to inspect.
- Choose Python Debugger: Debug Python File from the editor’s run/debug control.
- Set a breakpoint by clicking beside a line number, then start the debug session and inspect the paused program in the debugging interface.
Save a project configuration
For a session you will use repeatedly, create a Python debugger configuration in .vscode/launch.json. Choose the Python File configuration for a script, then press F5 to start debugging. VS Code also documents configurations for attaching by process ID. The available options and exact configuration depend on whether you are launching a program or attaching to one already running; consult Microsoft’s Python debugging in VS Code documentation for the configuration that matches your project.
Use debugpy from the command line or remotely
For command-line workflows, install debugpy in the Python environment you intend to use:
python -m pip install --upgrade debugpyVS Code documents running python -m debugpy with a listen or connect endpoint and a script, module, command, or process ID. The target and endpoint options depend on whether you are launching or attaching, so use the documented invocation for your case rather than copying an endpoint intended for a different setup. For remote debugging, configure the remote target and attach from the local VS Code interface. The documentation advises using a secure connection such as SSH where appropriate; do not expose a debug listener to an untrusted network.
Debug Python in PyCharm
- Open the project and set a breakpoint by clicking next to the relevant line.
- Start the project in Debug mode.
- When execution pauses, inspect variables and the current frame, step through statements, and continue execution from the debugger controls.
PyCharm’s debugger choice depends on the interpreter and workflow. JetBrains’ settings reference, displayed 14 July 2026, says debugpy is the default for Python 3.9 or later on local and WSL interpreters, with pydevd available as an alternative. PyCharm’s 2026.2 workflow documentation identifies cases not covered by debugpy, including some remote targets, attach-to-process workflows, Sphinx doctest, Scrapy, remote Jupyter notebooks, and certain manage.py tasks. JetBrains documents remote DAP attachment and alternative debugger selection as separate paths. Check the current PyCharm debugger settings and debug workflow for your interpreter, framework, and deployment arrangement rather than assuming the default mode supports it.
Recommended Free Tools
How to work through a debugging session
- Reproduce the behavior. Run the smallest relevant case you can, and note the input and result that differ from what you expect.
- Choose a stopping point. Put a breakpoint before the unexpected result, or use post-mortem debugging when an exception already identifies a failure point.
- Check the current frame. Inspect the inputs, local variables, and any expression that determines the next branch or result.
- Trace execution deliberately. Use step when you need to enter a function; use next when you want to stay in the current frame. Inspect the stack if you need the call path.
- Update your hypothesis. Once you see which value or branch is unexpected, adjust the code or input and rerun to confirm the cause.
- Remove temporary stops. Delete temporary
breakpoint()calls or disable breakpoints you no longer need before committing or running the program normally.
Troubleshooting common debugger problems
- The debugger does not stop at
breakpoint(). Confirm execution reaches that line and that the environment is using the default breakpoint behavior. If you are using a customized breakpoint configuration or debugger integration, check its settings. - VS Code runs the wrong Python. Check the selected workspace interpreter and the interpreter configured for the session. Install project dependencies and debugpy in the environment actually used to run the target.
- An attach session does not connect. Check that the target process is still running and that the attach method, process ID, endpoint, and interpreter match the chosen workflow. For remote sessions, use a secure connection and verify the remote target configuration.
- PyCharm’s default debugger does not support the target. Verify the interpreter version and whether the workflow is among the documented debugpy coverage gaps. Check JetBrains’ guidance for an alternative debugger or remote DAP attachment where relevant.
pdbattachment to a Python 3.14 process seems stuck. If the target is blocked in a system call or waiting for I/O, Python’s documentation says attachment may wait until another bytecode instruction executes or the process receives a signal.
Or skip the browser setup
For a website screenshot rather than a Python program debugging session, ScreenshotNeo is a website screenshot API and MCP server for developers. It uses one GET request to return a PNG, JPEG, WebP, or PDF. For example, save a WebP screenshot of a page with cURL:
Quick Recap
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for API options. Cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card.
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.
