Summarize this article with:
Print statements will only get you so far.
Learning how to debug Python in VSCode gives you real visibility into your code execution, variable states, and runtime errors without cluttering your files with temporary print() calls.
Visual Studio Code’s built-in Python debugger lets you set breakpoints, step through code line by line, and inspect variables at any point during execution.
This guide walks you through the complete debugging workflow in 10 steps.
You will learn how to configure launch.json, place breakpoints, use step controls, inspect variables, add watch expressions, and set conditional breakpoints that pause only when specific conditions are met.
Time required: 15 minutes.
How to Debug Python in VSCode
Debugging Python in VSCode is the process of identifying and fixing errors in Python code using Visual Studio Code’s built-in debugger tools.
Developers need this when tracking runtime errors, inspecting variables during execution, or stepping through code logic.
This guide covers 10 steps requiring 15 minutes and basic familiarity with VSCode.
Prerequisites
Before you start a debugging session, confirm these requirements:
- Visual Studio Code version 1.85 or later
- Python 3.8+ installed on your system
- Python extension for VSCode (ms-python.python)
- A .py file ready to test
- 10-15 minutes
You should know how to run Python in VSCode before attempting debug configurations.
If you work with virtual environments, learn how to activate venv in VSCode first.
Step One: How Do You Install the Python Extension in VSCode?
Open the Extensions view with Ctrl+Shift+X, search for “Python” by Microsoft, and click Install to add Python debugging tools and IntelliSense support to your editor.
Action
- Extensions sidebar: Click the square icon on the left Activity Bar or press Ctrl+Shift+X
- Search field: Type “Python” and select the extension by Microsoft (ms-python.python)
- Install button: Click the blue Install button, wait for completion
- Result: Extension appears in Installed list with Pylance included
Purpose
The Python extension provides debugpy, the debug adapter that connects VSCode to the Python interpreter.
Without it, breakpoints and variable inspection will not work.
Step Two: How Do You Open the Debug Panel in VSCode?
Access the Run and Debug panel by clicking the play icon with a bug in the Activity Bar or pressing Ctrl+Shift+D to display debugging controls and configuration options.
Action
- Activity Bar: Locate the play button with bug icon (fourth icon from top)
- Keyboard shortcut: Press Ctrl+Shift+D
- Panel display: Variables, Watch, Call Stack, and Breakpoints sections appear
- Result: “Run and Debug” button visible if no launch.json exists
Purpose
The debug panel centralizes all debugging workflow controls in one location.
You will use this panel to start sessions, monitor variables, and manage breakpoints throughout your codebase.
Step Three: How Do You Create a launch.json Configuration File?
Click “Run and Debug” in the Debug panel, select “Python Debugger” from the dropdown, then choose “Python File” to generate a launch.json configuration in the .vscode folder.
Action
- Run and Debug button: Click the blue button in the empty Debug panel
- Debugger selection: Choose “Python Debugger” from the command palette dropdown
- Configuration type: Select “Python File” for debugging the current active file
- Result: .vscode/launch.json created with default Python debug configuration
Purpose
The launch.json file stores your debug configuration settings.
It tells VSCode which Python interpreter to use, what arguments to pass, and where to find your script.
This file is part of your project’s software configuration management.
Default Configuration Example
“ { "version": "0.2.0", "configurations": [ { "name": "Python: Current File", "type": "debugpy", "request": "launch", "program": "${file}", "console": "integratedTerminal" } ] } `
Need a different interpreter? Learn how to change Python interpreter in VSCode.
Step Four: How Do You Set a Breakpoint in Your Python Code?
Click in the gutter area left of any line number to place a red dot, or press F9 with your cursor on the target line to create a breakpoint where code execution will pause.
Action
- Line gutter: Click the space immediately left of the line number
- Keyboard shortcut: Position cursor on line, press F9
- Red dot indicator: Confirms breakpoint is active
- Multiple breakpoints: Repeat on any lines you need to inspect
Purpose
Python breakpoints pause execution at specific lines so you can inspect variable states and program flow.
Place them before suspected bugs or at function entry points.
Step Five: How Do You Start a Debug Session?
Press F5 or click the green play button in the Debug panel to launch the debugger, which runs your Python script until it hits the first breakpoint or completes execution.
Action
- Start Debugging: Press F5 or click green play arrow in Debug panel
- Configuration selection: Choose “Python: Current File” if prompted
- Debug toolbar: Floating toolbar appears with step controls
- Result: Code runs until breakpoint, then pauses with yellow highlight
Purpose
Starting the debug session switches VSCode into debug mode.
The integrated terminal shows output while the editor highlights the current execution line.
You can also open the terminal in VSCode to see print statements during debugging.
Step Six: How Do You Use Step Controls During Debugging?
Use the debug toolbar buttons or keyboard shortcuts to step through Python code line by line: Step Over (F10) executes current line, Step Into (F11) enters functions, Step Out (Shift+F11) exits functions.
Action
- Step Over (F10): Execute current line, move to next line in same scope
- Step Into (F11): Enter function calls to debug inside them
- Step Out (Shift+F11): Complete current function, return to caller
- Continue (F5): Run until next breakpoint or end of program
- Stop (Shift+F5): Terminate debug session immediately
Purpose
Step controls let you trace code execution at your own pace.
Step Into is useful for debugging Python functions you wrote. Step Over skips library code.
Step Seven: How Do You Inspect Variables in the Debug Panel?
View all local and global variables in the Variables panel on the left sidebar during a paused debug session, or hover over any variable in the editor to see its current value.
Action
- Variables section: Expands automatically showing Locals and Globals
- Hover inspection: Mouse over any variable in code to see tooltip with value
- Expand objects: Click arrows to view nested properties and list items
- Modify values: Double-click any value to change it during execution
Purpose
Variable inspection reveals the actual state of your program at each breakpoint.
You can spot unexpected values, None assignments, or wrong data types instantly.
Step Eight: How Do You Add Watch Expressions?
Right-click any variable and select “Add to Watch” or click the + icon in the Watch section to monitor specific expressions that update automatically as you step through code.
Action
- Watch panel: Located below Variables in Debug sidebar
- Add expression: Click + icon, type any valid Python expression
- Complex expressions: Watch len(mylist), object.property, or calculations
- Auto-update: Values refresh at each breakpoint or step
Purpose
Watch expressions track specific values without searching through all variables.
Add expressions like len(data) or user.isauthenticated for quick monitoring.
Step Nine: How Do You Use the Debug Console?
Open the Debug Console panel at the bottom of VSCode during a paused session to execute Python commands, evaluate expressions, and interact with your program’s current state.
Action
- Panel location: View > Debug Console or Ctrl+Shift+Y
- Command input: Type Python expressions at the > prompt
- Evaluate variables: Type variable names to see values
- Execute code: Run any Python statement in current context
Purpose
The debug console lets you test fixes before changing code.
Try different values, call functions, or check conditions without restarting the debug session.
Step Ten: How Do You Set Conditional Breakpoints?
Right-click an existing breakpoint or the gutter and select “Add Conditional Breakpoint” to pause execution only when a specified Python expression evaluates to True.
Action
- Right-click breakpoint: Select “Edit Breakpoint” from context menu
- Expression condition: Enter condition like i > 100
orname == “test”
- Hit count: Set breakpoint to trigger after N hits
- Log message: Print to console without pausing (logpoint)
Purpose
Conditional breakpoints save time when debugging loops or high-frequency code paths.
Instead of stepping through 1000 iterations, pause only when your condition matches.
Verification
Confirm your Python debugging environment works correctly:
- Breakpoint hit: Yellow highlight appears on paused line
- Variables populated: Local variables display in sidebar
- Debug toolbar active: Step controls respond to clicks and shortcuts
- Console output: Print statements appear in Debug Console or Terminal
Run a simple test script with one breakpoint to verify everything connects properly.
Troubleshooting
Issue: Debugger Does Not Start
Solution: Check Python extension is installed and enabled. Verify launch.json exists in .vscode folder. Confirm Python interpreter is selected in bottom status bar.
Issue: Breakpoints Not Hitting
Solution: Ensure breakpoints show solid red dots, not hollow circles. Check that your code path actually executes the breakpoint line. Verify “justMyCode” setting in launch.json if debugging library code.
Issue: Python Interpreter Not Found
Solution: Press Ctrl+Shift+P, type “Python: Select Interpreter”, choose correct Python installation. Check PATH environment variable includes Python directory.
Access settings.json in VSCode to manually configure python.pythonPath if auto-detection fails.
Issue: launch.json Syntax Errors
Solution: Delete .vscode/launch.json and regenerate through Debug panel. VSCode highlights JSON errors with red squiggles. Check for missing commas or brackets.
Learn to enable error squiggles in VSCode for instant syntax feedback.
Related Processes
After mastering Python debugging, explore related software development workflows:
- How to run pytest in VSCode for automated testing
- How to debug React apps in VSCode for frontend debugging
- Unit testing practices to catch bugs before debugging
- Code coverage to identify untested code paths
- Defect tracking to document and manage bugs
Debugging fits within the broader software testing lifecycle alongside regression testing and other testing types.
Consider adopting test-driven development to reduce debugging time overall.
FAQ on How To Debug Python In VSCode
What extension do I need to debug Python in VSCode?
Install the Python extension by Microsoft (ms-python.python) from the Extensions marketplace.
This extension includes debugpy, the debug adapter that connects VSCode to your Python interpreter and enables breakpoints, variable inspection, and step controls.
Why are my breakpoints not working in VSCode?
Hollow circle breakpoints indicate unverified status. Check that your code path executes the breakpoint line.
Verify the Python interpreter is correctly selected and the debugger is running, not just the script.
What is the difference between Step Over and Step Into?
Step Over (F10) executes the current line and moves to the next line in the same scope.
Step Into (F11) enters function calls to debug inside them. Use Step Over for library functions you trust.
How do I debug a specific Python file instead of the current file?
Edit launch.json and change the “program” value from “${file}” to your specific file path.
Example: “program”: “${workspaceFolder}/src/main.py” targets main.py regardless of which file is open.
Can I change variable values during a debug session?
Yes. Double-click any variable value in the Variables panel during a paused state to modify it.
The new value applies immediately, letting you test different scenarios without restarting the debug session.
What is a conditional breakpoint in Python debugging?
A conditional breakpoint pauses execution only when a specified expression evaluates to True.
Right-click the breakpoint, select Edit Breakpoint, and enter a condition like count > 50 or user == None.
How do I debug Python code that uses command line arguments?
Add an “args” array to your launch.json configuration.
Example: “args”: [“–input”, “data.csv”, “–verbose”] passes these arguments to your script when the debug session starts.
Why does the debugger say Python interpreter not found?
VSCode cannot locate your Python installation. Press Ctrl+Shift+P, type “Python: Select Interpreter”, and choose the correct Python version.
Check your PATH environment variable if no interpreters appear in the list.
How do I debug Django or Flask applications in VSCode?
Select “Django” or “Flask” instead of “Python File” when creating launch.json.
VSCode generates framework-specific configurations with correct entry points, environment variables, and debug settings for web application debugging.
Can I debug Python code running in a virtual environment?
Yes. Select the virtual environment interpreter using Ctrl+Shift+P > Python: Select Interpreter.
Choose the Python executable inside your venv or conda environment. The debugger uses whichever interpreter is currently selected.
Conclusion
You now know how to debug Python in VSCode using the full range of tools available in the debug panel.
Setting up the Python extension and debug configuration takes minutes. The payoff lasts throughout your project.
The VSCode debugger handles everything from simple scripts to complex Django and Flask applications.
Use the Variables panel to track state changes. Add watch expressions for values you check repeatedly. Set conditional breakpoints when loops run thousands of iterations.
The debug console gives you a live Python environment at any pause point.
Skip the print() debugging habit. Step controls and variable inspection catch bugs faster and keep your code clean.
Start with a single breakpoint on your next Python project. Build from there.
Many of his resources are available on various design marketplaces and for free on Codepen.
Over the years, he's worked with a range of clients and contributed to design publications like Design Your Way, Designmodo, WebDesignerDepot, WPDean, and Speckyboy, and Slider Revolution among others.
- Android App Drawer vs Home Screen: Differences Explained - April 16, 2026
- 7 Things to Know Before Buying Refurbished Servers in 2026 - April 16, 2026
- iPhone Parental Controls: Complete Guide - April 15, 2026
