VS Code debugger: launch.json settings

1.0 The debugger and relative paths

VS Code’s debugger in default mode regards the root workspace (e.g., SI506/) as the current working directory.

In default mode the debugger recognizes paths relative to the workspace root directory like this:

filepath = './lectures/lecture_XX/lecture_XX.py' 

The debugger does not recognize paths relative to the Python file to be debugged.

lecture_XX.py
  data.csv       <- adjacent location not recognized
  input/
    data.json  <- subdirectory location not recognized

If you run the debugger in default mode and attempt to read a file employing a path relative to the Python file you wish to debug you will trigger a runtime FileNotFoundError.

Luckily, we can configure VS Code’s debugger to recognize filepaths relative to the location of the Python file we wish to debug (e.g., ./lecture_XX.py) by creating a custom launch.json file and adding a cwd (current working directory) setting that overrides the default debugger behavior.

2.0 The fix

❗ Before embarking on creating a launch.json file you must first enable VS Code’s “Execute in File Dir” terminal setting in order to avoid triggering runtime FileNotFoundError exceptions when attempting to run a Python script or program that reads from or writes to *.txt, *.csv and/or *.json files or imports a custom module. If you previously utilized the companion VS Code install guide to set up VS Code then you should have enabled the “Execute in File Dir” terminal setting. If you did not follow the guide or are unsure about whether or not you enabled the setting recheck the install guide.

1. Click on the Python file *.py that you want to debug. It will open in the editor pane.

2. On the left-hand vertical activity bar click the icon that features a triangular run button and bug.

3. The debugger pane will open. Under the blue “Run and Debug” button click the link “create a launch.json file”.

   

4. A command palette-like dropdown will appear over the editor pane prompting you to select a location for the launch.json file:

   Select a workspace folder to create a launch.json file in or add it to the workspace config file.

   The image below provides two options: the SI506/ directory or the workspace config file. Either location works for me. That said, I chose the SI506/ directory option which results in the creation of a SI506/.vscode directory to house the file.

   

5. Next, you will be prompted to select a debug configuration. Choose “Python File”.

   

6. The launch.json file will open in the editor pane after you choose “Python File” as the

   {
       // Use IntelliSense to learn about possible attributes.
       // Hover to view descriptions of existing attributes.
       // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
       "version": "0.2.0",
       "configurations": [
           {
               "name": "Python: Current File",
               "type": "python",
               "request": "launch",
               "program": "${file}",
               "console": "integratedTerminal",
               "justMyCode": true
           }
       ]
   }
   

7. Add the following key-value pair to the file between the “request” and “program” settings. Make sure that you add a trailing comma (,) after you insert the setting key-value pair. Then save the modified launch.json file.

   "cwd": "${fileDirname}",
   

8. The edited launch.json file should look like this:

   {
       // Use IntelliSense to learn about possible attributes.
       // Hover to view descriptions of existing attributes.
       // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
       "version": "0.2.0",
       "configurations": [
           {
               "name": "Python: Current File",
               "type": "python",
               "request": "launch",
               "cwd": "${fileDirname}",
               "program": "${file}",
               "console": "integratedTerminal",
               "justMyCode": true
           }
       ]
   }
   

9. You may also encounter a deprecation notice regarding the "type" configuration value when hovering over the squiggly yellow line under the "type": "python" key-value pair.

   

   If the key-value pair is highlighted, replace the value “python” with the string “debugpy”.

   {
       // Use IntelliSense to learn about possible attributes.
       // Hover to view descriptions of existing attributes.
       // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
       "version": "0.2.0",
       "configurations": [
           {
               "name": "Python: Current File",
               "type": "debugpy",
               "request": "launch",
               "program": "${file}",
               "cwd": "${fileDirname}",
               "console": "integratedTerminal",
               "justMyCode": true
           }
       ]
   }
   

10. Click “x” on the launch.json file tab to close the editor tab.

11. Click the activity bar’s debugger icon again to open the debugger pane. You should now see a green triangular run icon at the top of the debugger pane.

    

12. Click the activity bar’s debugger icon again to close the pane.

13. Declare victory. You should be ready to participate in the upcoming debugger demo.

💡 For more information regarding VS Codes’s debugger see VS Code’s “Debugging” page.