Debugging configurations for Python applications in Visual Studio Code (2023)

The Python extension supports debugging various types of Python applications. For a quick guide to basic debugging seeTutorial - Set up and run the debugger. also seeBottle guide. Both tutorials demonstrate basic skills such as setting breakpoints and stepping through code.

For general debugging functions such as checking variables, setting breakpoints, and other non-language-specific activities, seeFoutopsporingscode VS.

This article is mostly about Python-specific debuggingconfigurationsincluding the necessary steps for certain types of applications and remote debugging.

Initialize configurations

The configuration determines the behavior of VS code during a debugging session. Configurations are defined in arun.jsonthe file in which it is saved.vscodefolder in your workspace.

Remark: To change the debug configuration, your code must be stored in a folder.

First, select the file to run the debug configurationsStartsidebar view:

If you haven't defined any configuration yet, you will see a button to do soRun and debugand the link to create the configuration file (launch.json):

generaterun.jsonpython configuration file, follow these steps:

1. Choosecreate a launch.json filelink (shown in the image above) or useStart>Open configurationsmenu command.

2. The configuration menu opens from the command palette, allowing you to select the type of debug configuration for the open file. for nowSelect a configuration to debugselect from the menu that appearspython zaliha.

   Remark: Start a debug session from the debug panel,F5LubRun > Start Debuggingif there is no configuration, the debug configuration menu is also displayed, but no launch.json file is created.

3. Then the python extension creates and opens the filerun.jsonfile with a predefined configuration based on what you selected earlier, in this casepython zaliha. You can change configurations (for example to add arguments) and add custom configurations.

   

Configuration properties are discussed in detail in a section later in this articleStandard configuration and options. Other configurations are also described in this articleDebugging specific types of applications.

Additional configurations

By default, VS Code only displays the most common Python extension configurations. You can choose other recording configurationsrun.jsondoorAdd configurationnaredba shown in lists irun.jsoneditor. When you use the command, VS Code prompts you for a list of all available configurations (don't forget to include thePythonChoice):

ChoiceJoin process IDone gives the following result:

SeeDebugging specific types of applicationsfor more information on all these configurations.

During debugging, the status bar shows the current configuration and the current debug interpreter. Selecting a configuration displays a list from which you can select another configuration:

By default, the debugger uses the same interpreter selected for your workspace as other Python extension functions for VS Code. To use a different debug interpreter, set the value toPythonWrun.jsonfor correct debugging configuration. You can also select the named translator in the status bar to choose another.

Basic debugging

If you're just interested in debugging a python script, the easiest way is to select the down arrow next to the Run button in the editor and selectDebug python file in terminal.

If you want to debug a web application using Flask, Django, or FastAPI, the Python extension provides dynamically created debugging configurations based on the structure of your project inShow all auto-debug configurationsoption, throughRun and debugdisplay.

But if you want to debug other types of apps, you can run the debugger with the fileStartsee by clickingRun and debugbutton.

If no configuration is set, a list of debugging options is displayed. Here you can choose the right option to quickly debug your code.

Two common options are to usepython zalihaconfiguration to run or use the currently open python fileJoin process IDconfiguration to associate the debugger with a process that is already running.

For information about creating and using debug configurations, seeInitialize configurationsandAdditional configurationssections. After adding a configuration, you can select it from the drop-down list and start using itStart debuggingbutton.

Command line debugging

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

piton -m fotosporing--listen | --combine[:][--wait-for-customer][--configuration- ]...[--log-to] [--log-to-stderr]| -M| -C| --pid[]...

For example, you can run the debugger from the command line with a specific port (5678) and a script with the following syntax. This example assumes that the script has been running for a long time and has been skipped--waiting for the customerflag, which means the script does not wait for the client to connect.

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

Then use the following recording configuration from the VS Code Python extension.

{ "to do":"Python: Join Us", "tip":"Python", "Application":"attach", "combine": { "host":"Local Host", "Asylum":5678}}

Remark: Specifying a host is optional forListen, by default the address 127.0.0.1 is used.

To debug remote code or code running in a docker container on a remote machine or container, you must modify the previous CLI command to specify the host.

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

The associated configuration file then looks like this.

{ "to do":"Attach", "tip":"Python", "Application":"attach", "combine": { "host":"remote-computer-name",// replace this with the remote hostname "Asylum":5678}}

Remark: Note that if you specify a host value that is not127.0.0.1LubLocal hostopen a port to allow access from any machine, which creates security risks. If you are debugging remotely, make sure you take the appropriate precautions, such as using an SSH tunnel.

Remark:[]can be used to pass command line arguments to the running application.

Troubleshooting by connecting over a network connection

Fout tracking in local scripts

Sometimes you will need to debug a Python script that is called locally by another process. For example, you can debug a web server that runs different python scripts for specific processing tasks. In these cases, you should include the VS Code debugger in the script after you run it:

1. Start VS Code, open the folder or workspace that contains the script, and createrun.jsonfor that workspace, if it doesn't already exist.

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

   importdebugging#5678 is the default plugin to include in VS code debug configurations. Unless host and port are specified, the default host is 127.0.0.1debug.listen(5678)to print("Waiting for debugger to connect")debuppy.wait_for_client()debuppy.breakpoint()to print("break this rule")

3. Open terminal sTerminal: Create a new terminal, which activates the selected scripting environment.

4. In the terminal, install the debug package withpython -m pip install --upgrade debugpy.

5. For example, in the terminal, run python with the scriptpython3 mójskrypt.py. You should see "Waiting for debugger to be attached", which is included in the code, and the script stops atdebuppy.wait_for_client()phone call.

6. Switch toRun and debugdisplay (⇧⌘D(Windows, LinuxCtrl+Shift+D)), select the appropriate configuration from the Debugger drop-down list and start the debugger.

7. The debugger should stop atdebuppy.breakpoint()calls, from then on you can use the debugger normally. You also have the option to set other breakpoints in the script code via the UI instead of using themdebuppy.breakpoint().

Remote script debugging using SSH

Remote debugging allows you to step through a program locally in VS Code while it is running on a remote computer. There is no need to install VS Code on the remote computer. For added security, you may need a secure connection, such as SSH, to the remote computer while debugging.

Remark: Installation may be required on Windows computersWindows 10 OpenSSHhavesshTeams.

The steps below show the general procedure for setting up an SSH tunnel. An SSH tunnel allows you to work on your local computer as if you were working directly on a remote computer, more secure than opening a port for public access.

On the remote computer:

1. Enable port forwarding by opening the filesshd_configconfiguration file (in/etc/ssh/on Linux and below%programfiles(x86)%/openssh/etcin Windows) and add or change the following setting:

   Allow tcp forwarding yes

   Remark: The default value for AllowTcpForwarding is yes, so you may not need to make any changes.

2. If you want to add or changeAllow tcp forwarding, restart the SSH server. Running on Linux/macOSsudo restarts the ssh service; run on Windowsusluge.mscselect OpenSSH ilissdin the list of services and selectRestart.

On the local computer:

1. Create an SSH tunnel by runningssh -2 -L source port: localhost: destination port -i identity file user@remoteaddressuse the selected port forport of destinationand the associated username and IP address of the remote computerremote user@address. For example, to use port 5678 on IP address 1.2.3.4, the command would be:ssh -2 -L 5678:localhost:5678 -i identiteitsbestand gebruiker@1.2.3.4. You can specify the path to the identity file using-andflag.

2. Check if you see the prompt in the SSH session.

3. In your VS Code workspace, create a remote debugging configuration filerun.jsonfile by setting the port to match the port used in the filesshcommand and host forLocal host. you useLocal hosthere because you set up an SSH tunnel.

   { "to do":"Python: Join Us", "tip":"Python", "Application":"attach", "Asylum":5678, "host":"Local Host", "Pictures of the Road": [{ "local root":"${workspaceFolder}",// Tabs C:\Users\user1\project1 "external root":"." // To the current working directory ~/project1}]}

Debugging start

Now that the SSH tunnel is set up on the remote computer, you can start debugging.

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

2. Both computers: installdebuggingdoorpython -m pip install --upgrade debugpyyour environment (although using some form of virtual environment is not required, it is a recommended best practice).

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

   1. In your source code, add the following lines by replacing themAddresswith the IP address and port number of the remote computer (the IP address 1.2.3.4 is shown here for illustrative purposes only).

      importdebugging# Allow other computers to connect for debugging on this IP address and port.debuppy.listen(("1.2.3.4",5678))# Pause the program until the external debugger is connecteddebuppy.wait_for_client()

      IP address used inListenmust be the private IP address of the remote computer. You can then run the program normally and pause it until you add the debugger.

   2. Start a remote process with debuppy, for example:

      python3 -m debuppy --listen 1.2.3.4:5678 --wait for client -m mijn project

      This will launch the packagemy projectdoorpython3, with the private IP address of the remote computer1.2.3.4and listen at the port5678(you can also start a remote python process by specifying the file path instead of the-M, As./cześć.py).

4. local computer:Only if you have modified the source code on the remote computer as described above, then add to the source code a commented copy of the same code that you added on the remote machine. Adding these lines ensures that the source code on both machines matches line by line.

   #photo tracking import# Allow other computers to connect for debugging on this IP address and port.#debuppy.listen(('1.2.3.4', 5678))# Pause the program until the external debugger is connected#debuppy.wait_for_client()

5. Local computer: Switch toRun and debugdisplay (⇧⌘D(Windows, LinuxCtrl+Shift+D)) in Select VS codePython: Join usconfiguration

6. Local Machine: Set a breakpoint in your code where you want to start debugging.

7. Local machine: Run the VS code debugger with ModifiedPython: Join usconfiguration and the Start Debugging button. VS Code should stop at locally set breakpoints, allowing you to step through your code, inspect variables, and perform any other debugging actions. Expressions you enterDebug consolethey are also executed on the remote computer.

   Text output to stdout, fromto printstatement, appears on both computers. However, other output, such as graphical plots from packages such as matplotlib, only appear on the remote computer.

8. During remote debugging, the debug toolbar looks like this:

   

   (Video) How To Debug Python Code In Visual Studio Code (VSCode)

   On this toolbar, the Disconnect button (⇧F5(Windows, LinuxShift+F5)) stops debugging and allows the remote program to run completely. Restart button (⇧⌘F5(Windows, LinuxCtrl+Shift+F5)) restarts the debugger on the local computer, but it doesBORNrestart the program remotely. Use the restart button only if you have already restarted the remote program and need to reconnect the debugger.

Set configuration options

When you first createrun.json, there are two default configurations that run the active file in the editor on the integrated terminal (inside VS Code) or the remote terminal (outside VS Code):

{ "configurations": [{ "to do":"Python: current file (integrated terminal)", "tip":"Python", "Application":"start", "plan":"${stock}", "comfort":"integrated terminal"},{ "to do":"Python: huidig ​​inventory (external terminal)", "tip":"Python", "Application":"start", "plan":"${stock}", "comfort":"External terminal"}]}

Specific settings are described in the following sections. You can also add other settings such asargumentswhich are not included in standard configurations.

Advice: In a project, it is often useful to create a configuration that executes a specific startup file. For example, if you always want to runstart.pywith arguments-- luka 1593after running the debugger, create a configuration entry like this:

{ "to do":"Python: opstarten.py", "tip":"Python", "Application":"start", "plan":"${workspaceFolder}/startup.py", "arguments": ["--Asylum","1593"]},

To do

Contains the debug configuration name that appears in the VS Code drop-down list.

tip

Identifies the type of debugger being used; exit this settingPythonfor python code.

application

Specifies how to start debugging:

• start: starts the debugger on the file specified inplan
• enclose: add a debugger to an already running process. To seeRemote debuggingFor example.

plan

Provides a fully qualified path to the Python input module (startup file). Value${stock}, which is often used in default configurations, uses the currently active file in the editor. By specifying a specific startup file, you can always ensure that the program starts from the same starting point, regardless of which files are open. For example:

"plan":"/Gebruikers/Ik/Projecten/PokemonGo-Bot/pokemongo_bot/event_handlers/__init__.py",

You can also rely on the relative path from the root of the workspace. For example as root/Users/Me/Projects/PokemonGo-Botthen you can use the following example:

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

module

Provides the ability to specify the name of a debug module, such as with-Margument when run on the command line. For more information seePython.org

Python

The full path to the Python interpreter used for debugging.

If not specified, this setting defaults to the interpreter selected for the workspace, which is equivalent to using a value${command:python.interpreterPath}. To use another interpreter, specify the path in the filePythondebug configuration property.

You can also use a custom environment variable defined on each platform to include the full path to the Python interpreter you are using, eliminating the need for other directory paths.

If you need to pass arguments to the python interpreter, you can use a methodpythonArgsproperty.

pythonArgs

Specifies the arguments to pass to the Python interpreter using the syntax"pythonArgs": ["", "",...].

arguments

Specifies the arguments to pass to the Python program. Each element of the argument string, separated by a space, must be enclosed in quotation marks, for example:

"arguments": ["--Calm","--don't repeat","--Asylum","1593"],

stopOnEntry

When set toWHERE, terminates the debugger on the first line of the debugger. If omitted (default) or set toLIE, the debugger runs the program to the first breakpoint.

console

Determines how the program output is displayed, as long as it is set by defaultredirectOutputhave not been changed.

intention

There is more than one way to configure itStartuse the buttonintentionChoice. Set options tofault finding test, specifies that the configuration should be used when debugging tests in VS Code. However, if you set the option toterminal debugging, indicates that the configuration should only be used on openingRun the python filein the upper right corner of the editor (regardless of whetherRun the python fileLubDebug python-bestandbutton options are used).Remark:intentionoption cannot be used to run the debuggerF5LubRun > Start Debugging.

automatic reloading

It allows the debugger to automatically reload after a code change after the execution of the debugger reaches a breakpoint. To enable this feature set{"enable": true}as shown in the code below.

{ "to do":"Python: huidig​​​​consisted", "tip":"Python", "Application":"start", "plan":"${stock}", "comfort":"integrated terminal", "load automatically": { "clutch":WHERE}}

*Remark: When the debugger is reloaded, the code running during the import can be executed again. To avoid this situation, you can try to use only imports, constants and definitions in your module and put all your code in functions. Alternatively, you can also useif __name__=="__head__"control.

subprocesses

Specifies whether subprocess debugging should be enabled. DefaultLIE, Set upWHEREallow. For more information seedebugging on multiple targets.

cwd

Specifies the current working directory for the debugger, which is the base directory for all relative paths used in the code. If omitted by default${workspaceFolder}(open karte u VS kodu).

Let's say as an example${workspaceFolder}containscode_pycontain folderaplikacija.pyIAdeencontain foldersalary.csv. When you start the debuggerpy_code/app.py, the relative paths to the data file vary depending on the valuecwd:

redirectOutput

When set toWHERE(defaults to innerConsole) causes the debugger to print all program output to the VS Code Debug output window. If set toLIE(default for IntegratedTerminal and externalTerminal), program output is not displayed in the debugger output window.

This option is usually disabled when used"console": "integrated terminal"Lub"console": "External Terminal"because there is no need to duplicate the output in the debug console.

tylkoMójKod

After skipping or settingWHERE(default), limits debugging to user-written code only. setLIEto also enable debugging of standard library functions.

Django

When set toWHERE, activates debugging features specific to the Django web framework.

Sudo

When set toWHEREand is used with"console": "External Terminal", allows you to debug applications that require privilege escalation. You must use a remote console to intercept the password.

pyramid

When set toWHERE, launches the Pyramid appneededkeepTeams.

go

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

file env

Optional path to the file containing the environment variable definitions. SeeConfiguring the Python environment - environment variable definition file.

Bleed

If set toWHERE, enables debuggingvent monkey patched code.

jinja

When set toWHERE, activates program-specific debugging functionsJinjatemplate frames.

Breakpoints and logarithmic points

Python extension supportsbreaking pointsandapplication pointsto debug the code. For a quick guide to basic debugging and using breakpoints, seeTutorial - Set up and run the debugger.

Conditional breakpoints

Breakpoints can also be triggered based on an expression, the number of hits, or a combination of both. The Python extension supports the number of hits that are integers in addition to integers preceded by ==, >, >=, <, <=, and %. For example, you can set a breakpoint to fire after five hits by setting the number of hits to>5For more information seeconditional breakpointsin the main VS Code Debugging article.

Trigger a breakpoint in your code

In your python code you can calldebuppy.breakpoint()when you want to pause debugging during a debugging session.

Breakpoint check

The python extension automatically detects breakpoints set on non-executable rules such aspassagestatements or the middle of a multiline statement. In these cases, running the debugger moves the breakpoint to the nearest valid line to stop code execution at that point.

Debugging specific types of applications

The configuration drop-down list contains several options for common application types:

Special steps are also required for remote debugging and Google App Engine. For more information about debugging tests, seeTest.

To debug an application that requires administrative privileges, use"console": "External Terminal"and"sudo": "Where".

Debugging in the bottle

{ "to do":"Python: Kolba", "tip":"Python", "Application":"start", "module":"tracking", "Environment": { "FLASK_APP":"aplikacija.py"}, "arguments": [ "start", "--no debugger"], "jinja":WHERE},

As you can see, this specifies the configuration"env": {"FLASK_APP": "app.py"}and"args": ["pokreni", "--no-debugger". From"module": "bat"property is used insteadplan. (You can see"FLASK_APP": "${workspaceFolder}/app.py"wgoproperty, in which case the configuration is changed to refer only to the filename. Otherwise, you may see the error "Failed to import module C", where C is the drive letter.)

From"jinja": truththis setting also allows you to debug Jinja Flask's default templating engine.

To run the Flask development server in development mode, use the following configuration:

{ "to do":"Python: Flask (Developer Mode)", "tip":"Python", "Application":"start", "module":"tracking", "Environment": { "FLASK_APP":"aplikacija.py", "KOLBA_ENV":"development"}, "arguments": [ "start"], "jinja":WHERE},

Solve the problem

There are many reasons why the debugger does not work. Sometimes the debug console reveals specific reasons, but the main reasons are as follows:

• The path to the Python executable file is incorrect: check the path of the selected interpreter by running the filePython: Choose an interpretercommand and see the current value:

  

• There are invalid expressions in the monitor window: clear all expressions in the monitor window and run the debugger again.

• If you are working with a multi-threaded application that uses the native threading API (such as Win32Create a threadinstead of Python's threading API), it is now necessary to place the following source code at the beginning of each file you want to debug:

  importdebuggingdebuppy.debug_this_thread()

• Ako radite saLinuxWhen you try to apply the debugger to a running process, you may get a "timed out" error. To avoid this, you can temporarily run the following command:

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

Next steps

• Python environments- Specify which python interpreter is used for editing and debugging.
• Test- Set up test environments and discover, run and debug tests.
• Item reference- Explore the full range of Python-related settings in VS Code.
• General troubleshooting- Learn more about VS code debugging features.

19.01.2023