Tools and workflows

How to debug Python in VS Code with breakpoints

Pause before a Python line in VS Code, inspect local variables, step through the code, and fix breakpoints that never get hit.

Click in the margin next to an executable Python line to set a breakpoint, then press F5 in VS Code. If prompted, choose the Python debug configuration for the file. When execution pauses, inspect the variables the line is about to use. Step through the program until the first value differs from what you expected.

Find out why the loop skips the final value

Save the following as verify_total.py. It should count all three entries, but the last count is missing.

counts = [3, 4, 6]
total = 0

for count in counts[:-1]:
    total += count

print(total)

The expected total is 13 and the program prints 7. Place a breakpoint on total += count. Each pause shows which count the loop is about to add. The loop visits 3 and 4, then finishes. The problem is the slice in the loop header. Deleting the slice allows the loop to visit 6 as well.

On the first pause, count is 3 and total is 0. Press Continue to hit the same breakpoint on the second iteration. Now count is 4 and total is 3. A third press finishes the program. There is no third iteration to stop on.

Use the lowest level of detail you need

Step Over executes the current statement and stops at the next location in the current frame, when available. Use it when you trust a helper and want to see what it returns. Step Into enters a function call so you can inspect its inputs and local state. Step Out runs to the end of the current function and returns to the caller's context. Continue runs to a later breakpoint, exception, or program exit.

A breakpoint inside a frequently called helper can stop the program many times before the case you care about. Put it closer to the condition that distinguishes the faulty input. For supported debugger configurations, a simple condition such as count == 4 can narrow the pauses. Use an expression that inspects state without changing it.

Resolve breakpoints that never stop

A breakpoint can appear on a nonexecutable line where there is nothing to pause. Put it on an assignment in the function or loop you suspect and confirm that the program reaches that assignment. Check the file that the debugger actually launched. A configuration for the active file will run whichever file is active when you start, which is easy to overlook when your test file and main module are open together.

A missing import or data file before the breakpoint can terminate the run. Find the traceback in the console or terminal. Compare the debugger's interpreter, starting directory, and arguments with the working terminal command. Use the VS Code interpreter check if the debug configuration runs a different Python.

Use the stack to choose the right variables

The debugger's call stack lists active functions. If the display shows an unfamiliar variable, check which frame you selected. A helper may have a local variable named count, while its caller has a separate variable with that name. Changing frames lets you see the input at the call site and the working value inside the function. It is a way to inspect how information moved, not a change to how the program runs.

Write down the first mismatch. For the example, the mismatch occurs before addition because the loop only receives two values. You can inspect the list, loop variable, and subtotal, but the purpose is to identify which assumption failed. Once you have a clear mismatch, reproducing the same pause five more times rarely tells you more.

Debug side effects with a safe input and destination

A breakpoint delays execution, and a resumed program still performs its real actions. For a tool that writes files, select a small synthetic fixture and a temporary output directory. If a command would update shared data, use the project's fixture or approved testing environment. A debug console can evaluate code, so use it to inspect a value before trying expressions that write or mutate state.

Stepping can also affect timing. A race that disappears in a slow debug run still needs independent evidence, such as a recorded order of events from the relevant processes. Avoid using one paused run to claim a timing issue has been fixed.

Compare the failure with the passing case

Use the same launch context to run one case that produces the right answer and one that fails. If both start in the expected file and interpreter, compare the input values at the first divergent branch. For example, a function that counts accepted rows may skip an empty row intentionally, but reject the string "0" for an unrelated reason. Knowing which branch executed gives you a specific test to keep when the debugging session is over.

Give a repeatable case a named configuration

A small script without inputs may need no custom configuration. When the problem requires a particular entry point and arguments, create a project launch configuration that names them. Use repository-relative paths or workspace variables when possible. Keep personal credentials and sensitive sample data out of any configuration you commit.

Make one change at a time. If you update the configuration, Python version, and program logic in the same run and the error disappears, you cannot tell which change mattered. Once you know the intended behavior, record it in a small test. The breakpoint explained one faulty run, and the test can verify the corrected result whenever the code changes.

Sources and further reading

Related reading

Browse Tools and workflows · Explore project tutorials

Search PythonProjects.org