Debugging Python in WSL with VS Code: A Step-by-Step Guide
Debugging Python code is essential for identifying and fixing errors. When working with WSL (Windows Subsystem for Linux), the process can be a bit more complex. This article provides a comprehensive guide on how to configure VS Code for debugging Python applications running within WSL, ensuring a smooth and efficient workflow.
The Problem: Bridging the Gap
The core challenge lies in establishing a seamless connection between VS Code, which runs on Windows, and the Python interpreter within WSL. This requires configuring VS Code to understand the WSL environment, locate the Python interpreter, and execute debugging commands within the Linux context.
Setting Up the Environment
1. Install WSL:
- Ensure you have the latest version of Windows 10 or 11 installed.
- Open the Microsoft Store and search for "Ubuntu," or your preferred Linux distribution, and install it.
2. Install Python within WSL:
- Open your preferred WSL terminal (e.g., Ubuntu).
- Use the package manager to install Python:
sudo apt update && sudo apt install python3
3. Install VS Code and the Python Extension:
- Download and install VS Code from https://code.visualstudio.com/.
- Open VS Code and install the "Python" extension from the Marketplace.
Configuring VS Code for WSL Debugging
1. Remote-WSL Extension:
- Install the "Remote - WSL" extension from the VS Code Marketplace. This extension enables VS Code to connect and work with your WSL environment.
2. Connecting to WSL:
- Open VS Code and click on the "Remote - WSL" icon in the Activity Bar (the bar on the left side of VS Code).
- Select your preferred WSL distribution from the list. VS Code will now connect to your WSL environment.
3. Configure Python Interpreter:
- Open the command palette (Ctrl+Shift+P) and search for "Python: Select Interpreter."
- From the list, choose the Python interpreter you installed within WSL.
4. Debugging Settings:
- Open the "launch.json" file by navigating to "Run and Debug" > "Create a launch.json file."
- Modify the "launch.json" file with the following configuration:
{
"version": "0.2.0",
"configurations": [
{
"name": "Python: WSL",
"type": "python",
"request": "launch",
"program": "${file}",
"console": "integratedTerminal",
"cwd": "${workspaceFolder}",
"envFile": "${workspaceFolder}/.env",
"args": [],
"preLaunchTask": "g++ -g -o ${fileBasenameNoExtension} ${file}",
"runtimeArgs": [
"-m",
"ptvsd",
"--host",
"localhost",
"--port",
"5678",
"--wait"
],
"stopOnEntry": true,
"debugServer": 5678,
"pathMappings": [
{
"localRoot": "${workspaceFolder}",
"remoteRoot": "/mnt/c/Users/<Your Username>/<Your Project Folder>"
}
]
}
]
}
Explanation:
- "name": "Python: WSL": Specifies the configuration name for easy identification.
- "type": "python": Indicates the debugger type.
- "request": "launch": Defines the debugging action (launching the program).
- "program": "${file}": Specifies the file to be debugged.
- "console": "integratedTerminal": Uses the integrated VS Code terminal.
- "cwd": "${workspaceFolder}": Sets the working directory to the project folder.
- "envFile": "${workspaceFolder}/.env": Allows loading environment variables.
- "args": []: Adds any command-line arguments needed for your program.
- "preLaunchTask": "g++ -g -o ${fileBasenameNoExtension} ${file}": Defines a task to compile your code if needed.
- "runtimeArgs": [...]: Specifies arguments for the Python debugger (ptvsd).
- "stopOnEntry": true: Starts debugging when the program starts.
- "debugServer": 5678: Specifies the port for the debugging server.
- "pathMappings": [...]: Maps the local project folder to its corresponding path within WSL. Adjust the "remoteRoot" path to match your WSL project folder.
5. Debugging Your Code:
- Set breakpoints in your code by clicking on the line numbers.
- Press F5 or click the "Run and Debug" icon to start debugging.
Debugging Tips:
- Environment Variables: Ensure environment variables are correctly set within WSL.
- Path Mapping: Check the path mapping in "launch.json" to ensure accurate file access between VS Code and WSL.
- Error Handling: If you encounter issues, check the VS Code debug console for error messages.
Conclusion
By following these steps, you can configure VS Code to effectively debug Python code within WSL. This setup enables you to leverage the power of WSL's Linux environment for development, while enjoying the convenience of VS Code's debugging features. Remember to adjust the settings according to your specific project and environment configurations.
