Debug settings for Python apps in Visual Studio Code (2023)

The Python extension supports debugging many types of Python applications. For a quick walkthrough of basic debugging, seeTutorial - Configure and run the debugger. See also theJar-Tutorial. Both tutorials demonstrate core skills such as setting breakpoints and stepping through code.

For general debugging functions such as examining variables, setting breakpoints, and other non-language dependent activities, see the reviewVS-Code-Debugging.

This article is mainly about Python-specific debuggingsettings, including steps required for specific application types and remote debugging.

initialize settings

A setting controls the behavior of VS Code during a debug session. Settings are defined in alaunch.jsonFile stored in a.vscodefolders on your workspace.

Use: To change the debug configuration, your code must be saved in a folder.

To initialize debug settings, first select theto runSidebar view:

If you haven't configured any settings yet, you'll see a button to do so.run and debugand a link to create a configuration file (launch.json):

to generate alaunch.jsonPython settings file, do the following:

1. ChooseCreate a launch.json filelink (described in the image above) or use theto run>open settingsmenu command.

2. A configuration menu opens on the command palette, from which you can select the type of debug configuration you want for the opened file. for now inChoose a debug configurationmenu that appears, choosepython file.

   Use: start a debug session from the debug panel,F5orRun > Start DebuggingIf there is no configuration, the debug configuration menu will also be displayed, but no launch.json file will be created.

3. The Python extension creates and opens alaunch.jsonFile containing a predefined configuration based on your previous selection, in this casepython file. You can change settings (eg to add arguments) and also add custom settings.

   

Details of configuration properties are covered later in this article.Default configuration and options. Other settings are also described in this article belowDebug specific application types.

additional settings

By default, VS Code only shows the most common settings provided by the Python extension. You can choose other settings to includelaunch.jsonusing theadd configurationCommand displayed in the list and thelaunch.jsonEditor. When using the command, VS Code will ask for a list of all available configurations (make sure to use thePythonPossibility):

selection ofAppend with Process IDthe following result is reached:

VerDebug specific application typesfor details on all these settings.

During debugging, the status bar shows the current configuration and current debug interpreter. When you select the configuration, a list is displayed from which you can select a different configuration:

By default, the debugger uses the same interpreter selected for your workspace, as well as other features of the Python extension for VS Code. To use a different interpreter specifically for debugging, set the value toPythonnolaunch.jsonto the corresponding debugger configuration. Alternatively, select the named interpreter in the status bar to choose a different one.

basic debugging

If you are only interested in debugging a Python script, the easiest way is to select and select the down arrow next to the Run button in the editorDebug Python file in terminal.

If you want to debug a web application using Flask, Django or FastAPI, the Python extension provides dynamically created debug configurations based on your project structure in the sectionShow all auto debug settingsoption through whichrun and debugOpinion.

However, if you want to debug other types of applications, you can launch the debugger fromto runsee by clickingrun and debugKnopf.

If no settings are defined, you will see a list of debug options. Here you can select the appropriate option to quickly debug your code.

Two common options are to usepython fileConfiguration to run the currently open Python file or to use theAppend with Process IDConfiguration for attaching the debugger to an already running process.

For information on how to create and use debug configurations, see theinitialize settingseadditional settingsSections. Once a configuration has been added, it can be selected from the drop-down list and launched withstart debuggingKnopf.

Command line debugging

The debugger can also be run from the command line. The debugger command line syntax is as follows:

python -m debug--listen | --to connect[<host>:]<port>[--wait-client][--configure-<name> <value>]...[--log-to <Pfad>] [--log-to-stderr]<filename> | -m <module> | -c <code> | --pid <pid>[<arg>]...

For example, you can start the debugger from the command line with a specified port (5678) and a script with the following syntax. This example assumes the script will run for a long time and omits it.--waiting-client-flag, which means that the script does not wait for the client to connect.

python -m debugpy --listen 5678 ./myscript.py

Then you would use the following configuration to append from the VS Code Python extension.

{ "Name":"Python: Annexar", "Art":"Python", "Investigation":"attach", "to connect": { "Host":"Host local", "Porto":5678}}

Use: The host specification is optional forI hear, 127.0.0.1 is used by default.

If you want to debug remote code or code running in a Docker container on the remote machine or container, you need to change the previous CLI command to specify a host.

python -m debugpy --listen 0.0.0.0:5678 ./myscript.py

The associated config file would look like this.

{ "Name":"attach", "Art":"Python", "Investigation":"attach", "to connect": { "Host":"remote machine name",// Replace with the name of the remote computer "Porto":5678}}

Use: Note the following when specifying a host value other than127.0.0.1orhost locationThey open a door to allow access from any computer, which poses security risks. You should ensure that you use appropriate security precautions when debugging remotely, eg B. Using SSH tunnels.

Use:[<arg>]can be used to pass command line arguments to the application to launch.

Debug by attaching over a network connection

Local script debugging

There may be cases where you need to debug a Python script that is being called locally by another process. For example, you can debug a web server by running various Python scripts for specific processing jobs. In such cases, you need to attach the VS Code debugger to the script after launch:

1. Run VS Code, open the folder or workspace containing the script and create alaunch.jsonfor this workspace if none already exists.

2. Add the following in the script code and save the file:

   to importdebug#5678 is the default connector port in VS Code debug settings. Unless host and port are specified, host defaults to 127.0.0.1debugpy.listen(5678)pressure("Waiting for debugger attachment")debugpy.wait_for_client()debugpy.breakpoint()pressure('break on this line')

3. Open a terminal withTerminal: Create a new terminal, which activates the script's selected environment.

4. Install debugpy package in terminalpython -m pip install --upgrade debugpy.

5. In the terminal, start Python with the script, for example B.python3 meuscript.py. You should see the message "Waiting for debugger attach" included in the code and the script will stopdebugpy.wait_for_client()Phone call

6. switch torun and debugOpinion (⇧⌘D(Windows, LinuxCtrl+Shift+D)), select the appropriate configuration from the debugger drop-down list and start the debugger.

7. The debugger should stop at thisdebugpy.breakpoint()call, from this point you can use the debugger normally. You also have the option of setting other breakpoints in your script code using the UI instead of usingdebugpy.breakpoint().

Remote script debugging with SSH

Remote debugging lets you step through a program locally in VS Code while it's running on a remote computer. There is no need to install VS Code on the remote machine. For extra security, you may want or need to use a secure connection like SSH to the remote computer while debugging.

Use: On Windows computers, you may need to installWindows 10 OpenSSHhave itschCommand.

The following steps outline the general process for setting up an SSH tunnel. With an SSH tunnel, you can work on your local computer as if you were working directly on the remote computer, more securely than opening a port for public access.

No remote computer:

1. Enable port forwarding using thesshd_configconfiguration file (found in/etc/ssh/on Linux and below%Programmdateien(x86)%/openssh/etcon Windows) and adding or changing the following setting:

   AllowTcpForwarding ja

   Use: The default value for AllowTcpForwarding is yes, so you might not need to change it.

2. If you needed to add or changeAllowTcpForwarding, restart the SSH server. Run on Linux/macOSRestart sudo ssh service; run on windowsservices.msc, choose OpenSSH orsshdin the list of services and selectStarting over.

On the local computer:

1. Create an SSH tunnel by running itssh -2 -L sourceport:localhost:destinationport -i Identitätsdatei user@remoteaddress, with a port selected fordestination portand the corresponding username and IP address of the remote computeruser@remote address. For example, to use port 5678 on IP address 1.2.3.4, the command isssh -2 -L 5678:localhost:5678 -i user@1.2.3.4 identity file. You can specify the path to an identity file using-EUFlag.

2. Make sure you see a command prompt in the SSH session.

3. In the VS Code workspace, create a configuration for remote debugging on yourlaunch.jsonfile setting the port to match the port specified inschcommand and the host toohost location. you usehost locationhere because you configured the SSH tunnel.

   { "Name":"Python: Annexar", "Art":"Python", "Investigation":"attach", "Porto":5678, "Host":"Host local", "PfadMappings": [{ "localRoot":"${workbook}",// Arquivo C:\Users\user1\project1 ab "remoteRoot":"." // For current working directory ~/project1}]}

start debugging

Once an SSH tunnel is established to the remote computer, you can start debugging.

1. Both computers: Make sure identical source code is available.

2. Both computers: installdebugusepython -m pip install --upgrade debugpyin your environment (although not mandatory, using some form of virtual environment is a best practice).

3. Remote computer: There are two ways to specify how to connect to the remote process.

   1. In the source code, add and replace the following linesHouseholdby the IP address and port number of the remote computer (IP address 1.2.3.4 is shown here for illustration only).

      to importdebug# Allow other computers to connect to debugpy on this IP address and port.debugpy.listen(('1.2.3.4',5678))# Pause the program until a remote debugger is attacheddebugpy.wait_for_client()

      The IP address used inI hearit should be the remote computer's private IP address. You can start the program normally, which will stop it until the debugger attaches.

   2. Start the remote process via debugpy, for example:

      python3 -m debugpy --listen 1.2.3.4:5678 --wait-for-client -m meuprojeto

      This starts the packageMy projectusePython3, with the private IP address of the remote computer from1.2.3.4and listen in port5678(You can also start the remote python process by specifying a file path instead of using-m, as./hallo.py).

4. Facilities Computer:Only if you modified the source code on the remote computer as described above, then add in the source code a commented-out copy of the same code that was added on the remote machine. Adding these lines ensures that the source code is the same line-for-line on both machines.

   #import debug# Allow other computers to connect to debugpy on this IP address and port.#debugpy.listen(('1.2.3.4', 5678))# Pause the program until a remote debugger is attached#debugpy.wait_for_client()

5. Local computer: go torun and debugOpinion (⇧⌘D(Windows, LinuxCtrl+Shift+D)) in VS Code, select thePython: AnnexarConstruction

6. Local computer: Set a breakpoint in the code where you want to start debugging.

7. Local computer: Launch VS Code debugger with modifierPython: AnnexarConfiguration and the Start Debugging button. VS Code should pause at your locally defined breakpoints, allowing you to step through the code, examine variables, and perform all other debugging actions. Expressions you typeconsole debuggingare also run on the remote computer.

   Text output to stdout, abpressureInstructions appear on both computers. Other expenses like However, graphs from a package like matplotlib only appear on the remote machine.

8. During remote debugging, the debug toolbar appears as follows:

   

   (Video) Debugging Python in VSCode - 01 - Intro to Debugging in VSCode

   On this toolbar, the Disconnect button (⇧F5(Windows, LinuxShift+F5)) stops the debugger and allows the remote program to run to completion. The reset button (⇧⌘F5(Windows, LinuxCtrl+Shift+F5)) restarts the debugger on the local machine, but does soNotRestart the remote program. Use the restart button only if you have already restarted the remote program and need to reattach the debugger.

Set configuration options

When creating for the first timelaunch.json, there are two default configurations that run the active file in the editor in the built-in terminal (inside VS Code) or in the external terminal (outside VS Code):

{ "settings": [{ "Name":"Python: current file (integrated terminal)", "Art":"Python", "Investigation":"start", "Program":"${file}", "Console":"integrated terminal"},{ "Name":"Python: current file (external terminal)", "Art":"Python", "Investigation":"start", "Program":"${file}", "Console":"externesTerminal"}]}

Specific settings are described in the following sections. You can also add other settings, for exampleargument, which are not included in the default settings.

PrincipalNote: In a project, it is often useful to create a configuration that runs a specific initialization file. For example, if you always want to startstartup.pywith the arguments--Porta 1593When starting the debugger, create a configuration entry like this:

{ "Name":"Python: startup.py", "Art":"Python", "Investigation":"start", "Program":"${workspaceFolder}/startup.py", "Arguments": ["--Porto","1593"]},

Name

Provides the name for the debug configuration shown in the VS Code dropdown.

until

Identifies the type of debugger to use; leave this setting as isPythonfor Python code.

investigation

Specifies the mode to start debugging in:

• start: Start the debugger for the file specified inprogram
• add: Attach the debugger to an already running process. To seeRemote Debuggingfor example.

program

Provides the full path to the Python program input module (initialization file). the value that${file}, which is usually used in default settings, uses the file currently active in the editor. By specifying a specific startup file, you can be sure that you will always start your program with the same entry point, no matter what files are open. For example:

"Program":"/Users/Me/Projects/PokemonGo-Bot/pokemongo_bot/event_handlers/__init__.py",

You can also rely on a relative path from the root of the workspace. For example, if the root is/Users/Me/Projects/PokemonGo-BotThen you can use the following example:

"Program":"${workspaceFolder}/pokemongo_bot/event_handlers/__init__.py",

Module

Provides the ability to specify the name of a module to debug, similar to-mArgument when run from the command line. For more information, seePython.org

Python

The full path pointing to the Python interpreter to use for debugging.

If not specified, this setting defaults to the interpreter selected for your workspace, which is equivalent to using the value${command:python.interpreterPath}. To use a different interpreter, specify its path insteadPythonProperty of a debug configuration.

Alternatively, you can use a custom environment variable defined on each platform that contains the full path for the Python interpreter to use, eliminating the need for additional folder paths.

If you need to pass arguments to the Python interpreter, you can use the methodpythonArgsProperty.

pythonArgs

Specifies arguments to be passed to the Python interpreter using the syntax"pythonArgs": ["<arg 1>", "<arg 2>",...].

argument

Specifies the arguments to be passed to the Python program. Any element of the argument string separated by a space must be enclosed in double quotes, for example:

"Arguments": ["--still","--norepeat","--Porto","1593"],

stopOnEntry

When set toIs correct, stops the debugger at the first line of the program to be debugged. When omitted (default) or set toINCORRECT, the debugger runs the program at the first breakpoint.

console

Specifies how program output is displayed when using default values ​​forredirect outputare not modified.

purpose

There's more than one way to set it up.to runbutton with whichpurposePossibility. Put the optionDebug-Test, defines which setting should be used when debugging tests in VS Code. However, set the option todebug non-terminal, defines that the configuration should only be used when accessing theRun the Python filebutton in the top right corner of the editor (regardless of whether theRun the Python fileorDebugging a Python fileoptions provided by the button are used).Use: diepurposeThe option cannot be used to launch the debuggerF5orRun > Start Debugging.

reload automatically

Allows the debugger to automatically reload when changes are made to the code after the debugger execution hits a breakpoint. To enable this feature set{"enable": true}as shown no code to follow.

{ "Name":"Python: current file", "Art":"Python", "Investigation":"start", "Program":"${file}", "Console":"integrated terminal", "auto reload": { "enable":Is correct}}

*Use: When the debugger performs a reload, the code running on the import can be rerun. To avoid this situation, try to only use imports, constants and definitions in your module and place all code in functions. Alternatively, you can also usese __name__=="__main__"Verifications.

subprocesso

Indicates whether subprocess debugging should be enabled. The default isINCORRECT, To adjustIs correctenable. For more information, seeDebugging multiple destinations.

cwd

Specifies the current working directory for the debugger, which is the base folder for all relative paths used in code. If omitted, the default is${workbook}(the folder opened in VS Code).

Say as an example${workbook}contains apy_codefolder containsapp.py, it is aDatafolder containssalaries.csv. When starting the debuggerpy_code/app.py, the relative paths to the data file vary depending on the value ofcwd:

redirect output

When set toIs correct(the default value for internalConsole) causes the debugger to print all program output to the VS Code debug output window. when definedINCORRECT(default for IntegratedTerminal and externalTerminal) program output is not displayed in the debugger output window.

This option is normally disabled when used"console": "integriertesTerminal"or"console": "External terminal"since the output in the debug console does not need to be duplicated.

JustMyCode

When omitted or setIs correct(Default) Limits debugging to user-written code only. AdjustINCORRECTto allow debugging of standard library functions as well.

Django

When set toIs correct, enables debugging capabilities specific to the Django web framework.

sudo

When set toIs correctand used with"console": "External terminal", lets you debug applications that require elevation. Use of an external console is required to capture the password.

Pyramid

When set toIs correct, ensures that a Pyramid application starts withthe necessaryto maintaincommand.

environment

Sets optional environment variables for the debugger process in addition to system environment variables, which the debugger always inherits. The values ​​of these variables must be entered as strings.

envFile

Optional path to a file containing environment variable definitions. To seeConfiguring Python environments - environment variable definition file.

vent

when definedIs correct, allows debuggingCorrected code Gevent Monkey.

Jinja

When set toIs correct, enables specific debugging features for theJinjaModel-Framework.

Breakpoints e Logpoints

supported python extensionbreakpointseregistration pointsto debug code. For a quick walkthrough of basic debugging and using breakpoints, seeTutorial - Configure and run the debugger.

Conditional breakpoints

Breakpoints can also be set to trigger based on expressions, hit counts, or a combination of both. The Python extension supports counts of occurrences that are integers in addition to integers preceded by the operators ==, >, >=, <, <=, and %. For example, you can set a breakpoint to fire after five hits by setting a hit count of>5For more information, seeconditional breakpointsin the VS Code debugging main article.

Calling a breakpoint in code

In your Python code, you can calldebugpy.breakpoint()at any point where you want to stop the debugger during a debugging session.

Breakpoint Validation

The Python extension automatically detects breakpoints set on non-executable lines such ashappenstatements or in the middle of a multi-line statement. In these cases, running the debugger moves the breakpoint to the next valid line to ensure that code execution stops there.

Debug specific application types

The configuration dropdown offers several options for general application types:

Specific steps are also required for remote debugging and Google App Engine. See debug tests for detailsTest.

To debug an application that requires administrator privileges, use"console": "External terminal"e"sudo": "True".

Flask-Debugging

{ "Name":"Python: Bottle", "Art":"Python", "Investigation":"start", "Module":"Bottle", "environment": { "FLASK_APP":"app.py"}, "Arguments": [ "corre", "--no-debugger"], "jinja":Is correct},

As you can see, this setting specifies"env": {"FLASK_APP": "app.py"}e"args": ["run", "--no-debugger"]. Die"module": "piston"property is used instead ofprogram. (you can see"FLASK_APP": "${workspaceFolder}/app.py"on themenvironmentproperty, in this case change the setting to refer to the file name only. Otherwise, you may see the error "Cannot import module C" where C is a drive letter.)

Die"jinja": trueThe configuration also allows debugging for Flask's default Jinja template engine.

If you want to run Flask's development server in development mode, use the following configuration:

{ "Name":"Python: Flask (Development Mode)", "Art":"Python", "Investigation":"start", "Module":"Bottle", "environment": { "FLASK_APP":"app.py", "FLASK_ENV":"Development"}, "Arguments": [ "corre"], "jinja":Is correct},

Problems solution

There are many reasons why the debugger might not work. Sometimes the debug console shows certain causes, but the main ones are as follows:

• The path to the Python executable is incorrect: check the chosen interpreter path by typing thePython: choose interpreterCommand and display of current value:

  

• There are invalid expressions in the watch window: clear all expressions from the watch window and restart the debugger.

• If you are working with a multithreaded application that uses native threading APIs (e.g. Win32create a topicfunction instead of Python's threading APIs), you currently need to paste the following source code at the top of the file you want to debug:

  to importdebugdebugpy.debug_this_thread()

• If you work with aLinuxSystem, you may get a "timed out" error when trying to debug a running process. To avoid this, you can temporarily run the following command:

  Eco0 | sudo tee /proc/sys/kernel/yama/ptrace_scope

Next steps

• Python environments- Control which Python interpreter is used for editing and debugging.
• Test- Configure test environments and discover, run, and debug tests.
• settings reference- Explore the full range of Python-related settings in VS Code.
• general debugging- Learn about VS Code's debugging features.

13.07.2022