Debugging Python in VSCode: Step-by-Step Guide for Beginners

You will encounter debugging while developing backend systems, web applications, or automation scripts - it's an inevitable step in the development life cycle. Debugging is a necessary step preceding any delivery of a software product. The Python ecosystem academic is different in that you may not see your errors until you are running the code.

Having a stable way to debug your Python code is very important for continuing your development journey. Luckily, as a developer, probably one of the best possible setups you could have is VSCode Python Debugger.

In this guide, you will learn how to set up and use the VSCode debug environment, explore a typical Python debug flow, and learn how to avoid some common pitfalls that can slow down your development.

Why Use VSCode for Python Debugging?

Use VSCode for Python Debugging

VSCode has undoubtedly become the code editor of choice among developers for speed and capabilities. Below are some of the reasons it excels for Python debugging:

Lightweight by design, heavyweight by capabilities
Microsoft Python extension: Smart code completion (IntelliSense), code linting, and debugger support
Git and integrated terminal
Cross-platform capabilities

More Context and Comparison with Other Tools

PyCharm is powerful but resource-heavy
Jupyter Notebooks are great for Data Science, but not debugging apps
Atom/Sublime do not provide debugging capabilities out of the box

Configuring the VSCode debugger for Python

Download Visual Studio Code
Download the Microsoft Python extension
Select your python interpreter (Ctrl+Shift+P → "Python: Select Interpreter")
If you would like to, you can install debugpy, pdb, or ipdb
Activate your virtual environment, if applicable

Creating Your First Debug Configuration

In order to further customize your debugging sessions, you will need a launch.json file under the .vscode folder.

Configuring a launch file:

Go to the Debug tab (Run and Debug)
Click “Create a launch.json file”
When prompted, select “Python”

Example

{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Current File",
      "type": "python",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "args": ["--example", "value"]
    }
  ]
}

Debugging Python Code Using VSCode

To get started debugging, hit F5 or click the green "Run" button.

Essential Features of Debug Interface

Breakpoints
Step in / step over / step out
Variable explorer
Call stack
Watch window
Hover inspection
Debug console (for live evaluations)

Using Breakpoints to debug like a pro

Breakpoint features:

Add / remove a breakpoint with F9 or by using the "Breakpoint" icon in the sidebar.
Set conditional breakpoints (e.g.: x > 10).
Create logpoints where you can print messages to the output without stopping the execution.
Set temporary breakpoints.
Set hit counts: break after hitting the breakpoint a certain number of times.

Advanced Debugging Techniques

Debugging remotely

Utilize debugpy.listen()
Connect via Remote SSH

Flask / Django applications

Use "args": ["runserver"] or "django": true in your config

Multithreaded debugging

See all threads in the call stack
Very useful for yours, background jobs and asyncio

Attaching to processes

Attach to already running scripts or services

Debugging unit tests

Integrate with pytest or unittest
By running it in the Testing tab or creating a debug configuration for your tests

Debugging Jupyter Notebooks in VSCode

Use %debug in a code cell
Click the debug icon in the top-right corner
You can see the call stack and variables, the same way as if you were debugging a script.

Command Palette & Keyboard Shortcuts

Boost productivity with key bindings:

F5: Start debugging
F9: Toggle breakpoint
F10: Step over
F11: Step into
Shift+F11: Step out
Ctrl+Shift+D: Open debug panel
Ctrl+Shift+P: Access Command Palette

Common Python Debugging Errors in VSCode & Solutions

Breakpoints not hitting
If breakpoints are not being hit, ensure you have saved your file, selected the correct Python interpreter and that you have configured the debugger properly.

Debugger not starting
If the debugger is not starting, check your launch.json file for mistakes and verify that you have correctly installed the Python extension and debugger.

Path-related errors
If your script cannot find files or directories, change your "cwd" (current working directory) in your debugger configuration file.

Environment variables not loading
Ensure your config includes "envFile": "${workspaceFolder}/.env" to load variables correctly from a .env file.

Best Strategies for Debugging Python in VSCode

Make use of logging rather than print statements
Logging will give you many more options, and control while keeping your debug output clean and structured.
Add a linter like pylint or flake8
Linters catch regular problems before you even run the code saving time and effort with debugging later.
Write tests before debugging
Unit tests allow you to dial in on the source of the bug quickly to also help minimize regressions.
Break your code into smaller functions or modules
Modular code will be easier to reason about, test, and debug when things go wrong.
Use .env files to manage your configurations
Drill down your environment variables so they do not live in every codebase while maintaining consistency while debugging.

Bonus: Debugging in Containers and Virtual Environments

Use Remote - Containers extension for Docker
Attach debugger to running container via debugpy
For WSL, activate the right environment in terminal
Always ensure the correct interpreter is selected

Conclusion

Using the vscode Python Debugging will help you maintain the hero status of debugging your Python code. With all its features, breakpoints, variable tracking and interaction with all your Git and terminal, it is an invaluable tool for any modern-day Python developer.

You no longer have to rely on print statements to debug your Python code, and you are now able to debug with higher quality. Especially when you pair VSCode with some smart tools like Keploy. Keploy captures your actual API traffic for your application and it works on it automatically generating test cases for you, allowing you to catch bugs even earlier in development and help prevent regression bugs when deploying your application!

Using Keploy with VSCode, you can debug your simple script or a obviously buggy backend simultaneously and feel confident that you're going to debug smarter, test faster, and ship smarter.

Frequently Asked Questions (FAQs)

What is the VSCode Python Debugger?

VSCode Python Debugger is an integrated tool for Microsoft Visual Studio Code to enable you to inspect your Python code step by step, set breakpoints, inspect variables, and find issues without placing a bunch of print statements in your code!

How do I get started debugging in VSCode for Python?

First, install the Microsoft Python Extension. You then have to load your Python file, and click on F5 or "Run and Debug" button. If you'd like to get more granular control, you can create a .vscode/launch.json file to customize your debugging configuration.

Why aren't my breakpoints working in VSCode?

Some reasons your breakpoints might not be hit is: You happen not to save your file, the Python interpreter you selected is wrong, or you didn't launch your script via the debugger. You must make sure your file is saved and that you launch your app with the debug configuration.

Can I debug a Flask or Django application in VSCode?

Yes! You need to set "django": true in your launch.json configuration for Django. For Flask, you just add your app.py under "program" as well as "args": ["run"]. Both activities are fully supported in VSCode proper debugging launch.json setup.

What are some best -known practices for Python debug in VSCode?

Take advantage of loggers instead of standard print statements, write your tests earlier rather than later, split up your code into functions/modules, enable linters such as pylint, and don't forget to use conditional breakpoint and watch expressions to speed up your debugging.

VSCode Python Debugging Tips & Tricks