VS Code Python Debugging Tutorial

This tutorial is designed to help those who are not familiar with VS Code Python debugging. You'll learn how to set up your debugging environment, use breakpoints, inspect variables, and master essential debugging techniques.

Prerequisites

• Visual Studio Code installed
• Anaconda or Miniconda installed
• Basic knowledge of Python

Environment Setup

1. Create Conda Environment

First, create a new conda environment for this tutorial:

conda create -n vscode-debug-tutorial python=3.10 -y

2. Activate the Environment

conda activate vscode-debug-tutorial

3. Install Required Packages

you should be on the following workspace: python-debugging-with-vscode

conda install numpy pandas matplotlib -y
pip install requests
pip install torch==2.1.0

Alternatively, you can use the provided environment.yml file:

conda env create -f environment.yml

4. Configure VS Code

Install Python Extension

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "Python" by Microsoft
4. Click Install

Set Up launch.json for Debugging

VS Code uses a launch.json file to configure debugging sessions. Let's create one:

1. Open the tutorial folder in VS Code
2. Go to the Run and Debug view (Ctrl+Shift+D / Cmd+Shift+D)
3. Click "create a launch.json file"
4. Select "Python" as the debugger
5. Select "Python File" as the configuration

Alternatively, create .vscode/launch.json manually with this content:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: Current File",
            "type": "debugpy",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "justMyCode": true
        }
    ]
}

What these settings mean:

• "program": "${file}" - Debug the currently open Python file
  • ${file} is a VS Code variable that automatically resolves to the full path of the file you have open in the editor
  • Example: If you have 01_basic_debugging.py open, ${file} becomes .../python-debugging-with-vscode/01_basic_debugging.py
  • This allows you to debug any Python file just by opening it and pressing F5
• "console": "integratedTerminal" - Show output in VS Code's integrated terminal
• "justMyCode": true - Only debug your code, skip library code

Note: We'll add command-line arguments configuration later in the tutorial.

Select Python Interpreter

1. Open the Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
2. Type "Python: Select Interpreter"
3. Choose the vscode-debug-tutorial conda environment
   • It should appear as: Python 3.10.x ('vscode-debug-tutorial')

Verify Installation

Open the integrated terminal in VS Code (Ctrl+ / Cmd+) and run:

python --version
conda info --envs

You should see Python 3.10.x and your active environment should be vscode-debug-tutorial.

Tutorial Structure

This tutorial consists of 4 focused Python scripts covering essential debugging concepts:

1. 01_basic_debugging.py - Introduction to breakpoints, step-through debugging, and the Variables panel
2. 02_debugging_loops.py - Debugging loops, iterations, and using conditional breakpoints
3. 03_debugging_functions.py - Debugging function calls, inspecting arguments and return values
4. 04_debugging_torch.py - Debugging PyTorch models, tensors, and gradients

Quick Start

1. Clone or navigate to this tutorial directory
2. Set up your conda environment (see above)
3. Open the tutorial folder in VS Code
4. Start with 01_basic_debugging.py
5. Follow the instructions in each script

Debugging Basics

Setting Breakpoints

• Click in the left margin (gutter) next to a line number, or press F9
• A red dot indicates an active breakpoint

Debug Controls

• F5 - Start/Continue debugging
• F10 - Step Over (execute current line)
• F11 - Step Into (enter function calls)
• Shift+F11 - Step Out (exit current function)
• Ctrl+Shift+F5 - Restart debugging
• Shift+F5 - Stop debugging

Debug Views

• Variables - View and modify variable values
• Watch - Monitor specific expressions
• Call Stack - See the execution path
• Breakpoints - Manage all breakpoints
• Debug Console - Execute code during debugging

Understanding the Call Stack

The Call Stack shows the sequence of function calls that led to the current point in execution. It's read from bottom to top:

main()                    ← Bottom (first function called)
  ↓
calculate_statistics()    ← Middle (called by main)
  ↓
np.std()                 ← Top (current execution point)

How to read it:

• Top frame - Where the debugger is currently paused
• Bottom frame - The entry point of your program (usually main() or module level)
• Click any frame - View variables and code at that point in execution

Example: If you're debugging and the call stack shows:

> numpy.std (line 123)
  calculate_statistics (line 37)
  main (line 60)
  <module> (line 115)

This means:

1. Your script started at line 115 (module level)
2. Called main() at line 60
3. main() called calculate_statistics() at line 37
4. calculate_statistics() called numpy.std() where you're currently paused at line 123

Tip: Click on different frames to see how variables change at each level of the call hierarchy!

Troubleshooting

Python Interpreter Not Found

If VS Code can't find your conda environment:

1. Restart VS Code after creating the environment
2. Manually specify the interpreter path:
   • On Linux/Mac: ~/anaconda3/envs/vscode-debug-tutorial/bin/python
   • On Windows: %USERPROFILE%\anaconda3\envs\vscode-debug-tutorial\python.exe

Debugger Not Stopping at Breakpoints

1. Make sure you're running in debug mode (F5), not just running the script
2. Verify breakpoints are enabled (they should be red, not gray)
3. Check that the code is actually being executed

Import Errors

If you encounter import errors:

conda activate vscode-debug-tutorial
pip install <missing-package>

Additional Resources

• VS Code Python Debugging Documentation
• Python Debugger (pdb) Documentation
• Conda Documentation

Deactivating the Environment

When you're done:

conda deactivate

Removing the Environment

To completely remove the tutorial environment:

conda env remove -n vscode-debug-tutorial

---

Happy Debugging! 🐛🔍