- Remote development over SSH
- Install the extension
- Remote — SSH
- Create a virtual machine
- Set up SSH
- Create an SSH key
- Add SSH key to your VM
- Auto shutdown
- Connect using SSH
- Create your Node.js application
- Install Node.js and npm
- Install the Express generator
- Create a new application
- Run the application
- Port forwarding
- Edit and debug
- Ending your SSH connection
- Python debugging in VS Code
- Initialize configurations
- Additional configurations
- Basic debugging
- Command line debugging
- Debugging by attaching over a network connection
- Local script debugging
- Remote script debugging with SSH
- Set configuration options
- Breakpoints and logpoints
- Conditional breakpoints
- Invoking a breakpoint in code
- Breakpoint validation
- Debugging specific app types
- Flask debugging
Remote development over SSH
This tutorial walks you through creating and connecting to a virtual machine (VM) on Azure using the Visual Studio Code Remote — SSH extension. You’ll create a Node.js Express web app to show how you can edit and debug on a remote machine with VS Code just like you could if the source code was local.
Note: Your Linux VM can be hosted anywhere — on your local host, on premise, in Azure, or in any other cloud, as long as the chosen Linux distribution meets these prerequisites.
To get started, you need to have done the following steps:
- Install an OpenSSH compatible SSH client (PuTTY is not supported).
- Install Visual Studio Code.
- Have an Azure subscription (If you don’t have an Azure subscription, create a free account before you begin).
Install the extension
The Remote — SSH extension is used to connect to SSH hosts.
Remote — SSH
With the Remote — SSH extension installed, you will see a new Status bar item at the far left.
The Remote Status bar item can quickly show you in which context VS Code is running (local or remote) and clicking on the item will bring up the Remote — SSH commands.
Create a virtual machine
If you don’t have an existing Linux virtual machine, you can create a new VM through the Azure portal. In the Azure portal, search for «Virtual Machines», and choose Add. From there, you can select your Azure subscription and create a new resource group, if you don’t already have one.
Note: In this tutorial, we are using Azure, but your Linux VM can be hosted anywhere, as long as the Linux distribution meets these prerequisites.
Now you can specify details of your VM, such as the name, the size, and the base image. Choose Ubuntu Server 18.04 LTS for this example, but you can choose recent versions of other Linux distros and look at VS Code’s supported SSH servers.
Set up SSH
There are several authentication methods into a VM, including an SSH public/private key pair or a username and password. We recommend using key-based authentication (if you use a username/password, you’ll be prompted to enter your credentials more than once by the extension). If you’re on Windows and have already created keys using PuttyGen, you can reuse them.
Create an SSH key
If you don’t have an SSH key pair, open a bash shell or the command line and type in:
This will generate the SSH key. Press Enter at the following prompt to save the key in the default location (under your user directory as a folder named .ssh ).
You will then be prompted to enter a secure passphrase, but you can leave that blank. You should now have a id_ed25519.pub file which contains your new public SSH key.
Note: If you are using a legacy system that doesn’t support the Ed25519 algorithm, you can use rsa instead: ssh-keygen -t rsa -b 4096 .
Add SSH key to your VM
In the previous step, you generated an SSH key pair. Select Use existing public key in the dropdown for SSH public key source so that you can use the public key you just generated. Take the public key and paste it into your VM setup, by copying the entire contents of the id_ed25519.pub in the SSH public key. You also want to allow your VM to accept inbound SSH traffic by selecting Allow selected ports and choosing SSH (22) from the Select inbound ports dropdown list.
A cool feature of using Azure VMs is the ability to enable auto shutdown (because let’s face it, we all forget to turn off our VMs…). If you go to the Management tab, you can set the time you want to shut down the VM daily.
Select Review and Create, then Create, and Azure will deploy your VM for you!
Once the deployment is finished (it may take several minutes), go to the new resource view for your virtual machine.
Connect using SSH
Now that you’ve created an SSH host, let’s connect to it!
You’ll have noticed an indicator on the bottom-left corner of the Status bar. This indicator tells you in which context VS Code is running (local or remote). Click on the indicator to bring up a list of Remote extension commands.
Choose the Remote-SSH: Connect to Host command and connect to the host by entering connection information for your VM in the following format: user@hostname .
The user is the username you set when adding the SSH public key to your VM. For the hostname , go back to the Azure portal and in the Overview pane of the VM you created, copy the Public IP address.
Before connecting in Remote — SSH, you can verify you’re able to connect to your VM via a command prompt using ssh user@hostname .
Note: If you run into an error ssh: connect to host port 22: Connection timed out , you may need to delete NRMS-Rule-106 from the Networking tab of your VM:
Set the user and hostname in the connection information text box.
VS Code will now open a new window (instance). You’ll then see a notification that the «VS Code Server» is initializing on the SSH Host. Once the VS Code Server is installed on the remote host, it can run extensions and talk to your local instance of VS Code.
You’ll know you’re connected to your VM by looking at the indicator in the Status bar. It shows the hostname of your VM.
The Remote — SSH extension also contributes a new icon on your Activity bar, and clicking on it will open the Remote explorer. From the dropdown, select SSH Targets, where you can configure your SSH connections. For instance, you can save the hosts you connect to the most and access them from here instead of entering the user and hostname.
Once you’re connected to your SSH host, you can interact with files and open folders on the remote machine. If you open the integrated terminal ( ⌃` (Windows, Linux Ctrl+` ) ), you’ll see you’re working inside a bash shell while you’re on Windows.
You can use the bash shell to browse the file system on the VM. You can also browse and open folders on the remote home directory with File > Open Folder.
Create your Node.js application
In this step, you will create a simple Node.js application. You will use an application generator to quickly scaffold out the application from a terminal.
Install Node.js and npm
From the integrated terminal ( ⌃` (Windows, Linux Ctrl+` ) ), update the packages in your Linux VM, then install Node.js, which includes npm, the Node.js package manager.
You can verify the installations by running:
Install the Express generator
Express is a popular framework for building and running Node.js applications. You can scaffold (create) a new Express application using the Express Generator tool. The Express Generator is shipped as an npm module and installed by using the npm command-line tool npm .
The -g switch installs the Express Generator globally on your machine so that you can run it from anywhere.
Create a new application
You can now create a new Express application called myExpressApp by running:
The —view pug parameters tell the generator to use the pug template engine.
To install all of the application’s dependencies, go to the new folder and run npm install .
Run the application
Last, let’s ensure that the application runs. From the terminal, start the application using the npm start command to start the server.
The Express app by default runs on http://localhost:3000. You won’t see anything in your local browser on localhost:3000 because the web app is running on your virtual machine.
To be able to browse to the web app on your local machine, you can leverage another feature called Port forwarding.
To be able to access a port on the remote machine that may not be publicly exposed, you need to establish a connection or a tunnel between a port on your local machine and the server. With the app still running, open the SSH Explorer and find the Forwarded Ports view. Click on the Forward a port link and indicate that you want to forward port 3000:
Name the connection «browser»:
The server will now forward traffic on port 3000 to your local machine. When you browse to http://localhost:3000, you see the running web app.
Edit and debug
From the Visual Studio Code File Explorer ( ⇧⌘E (Windows, Linux Ctrl+Shift+E ) ), navigate to your new myExpressApp folder and double-click the app.js file to open it in the editor.
When you start typing, you’ll get smart completions for the object methods and properties.
Set a breakpoint on line 10 of app.js by clicking in the gutter to the left of the line number or by putting the cursor on the line and pressing F9 . The breakpoint will be displayed as a red circle.
Now, press F5 to run your application. If you are asked how to run the application, choose Node.js.
The app will start, and you’ll hit the breakpoint. You can inspect variables, create watches, and navigate the call stack.
Press F10 to step or F5 again to finish your debugging session.
You get the full development experience of Visual Studio Code connected over SSH.
Ending your SSH connection
You can end your session over SSH and go back to running VS Code locally with File > Close Remote Connection.
Congratulations, you’ve successfully completed this tutorial!
Next, check out the other Remote Development extensions.
Or get them all by installing the Remote Development Extension Pack.
Python debugging in VS Code
The Python extension supports debugging of several types of Python applications. For a short walkthrough of basic debugging, see Tutorial — Configure and run the debugger. Also see the Flask tutorial. Both tutorials demonstrate core skills like setting breakpoints and stepping through code.
For general debugging features such as inspecting variables, setting breakpoints, and other activities that aren’t language-dependent, review VS Code debugging.
This article mainly addresses Python-specific debugging configurations, including the necessary steps for specific app types and remote debugging.
A configuration drives VS Code’s behavior during a debugging session. Configurations are defined in a launch.json file that’s stored in a .vscode folder in your workspace.
Note: To change debugging configuration, your code must be stored in a folder.
To initialize debug configurations, first select the Run view in the sidebar:
If you don’t yet have any configurations defined, you’ll see a button to Run and Debug and a link to create a configuration (launch.json) file:
To generate a launch.json file with Python configurations, do the following steps:
Select the create a launch.json file link (outlined in the image above) or use the Run > Open configurations menu command.
A configuration menu will open from the Command Palette allowing you to choose the type of debug configuration you want for the opened file. For now, in the Select a debug configuration menu that appears, select Python File.
Note: Starting a debugging session through the Debug Panel, F5 or Run > Start Debugging when no configuration exists will also bring up the debug configuration menu, but will not create a launch.json file.
The Python extension then creates and opens a launch.json file that contains a pre-defined configuration based on what you previously selected, in this case, Python File. You can modify configurations (to add arguments, for example), and also add custom configurations.
The details of configuration properties are covered later in this article under Standard configuration and options. Other configurations are also described in this article under Debugging specific app types.
By default, VS Code shows only the most common configurations provided by the Python extension. You can select other configurations to include in launch.json by using the Add Configuration command shown in the list and the launch.json editor. When you use the command, VS Code prompts you with a list of all available configurations (be sure to select the Python option):
Selecting the Attach using Process ID one yields the following result:
See Debugging specific app types for details on all of these configurations.
During debugging, the Status Bar shows the current configuration and the current debugging interpreter. Selecting the configuration brings up a list from which you can choose a different configuration:
By default, the debugger uses the same interpreter selected for your workspace, just like other features of Python extension for VS Code. To use a different interpreter for debugging specifically, set the value for python in launch.json for the applicable debugger configuration. Alternately, select the named interpreter on the Status Bar to select a different one.
If you’re only interested in debugging a Python script, the simplest way is to select the down-arrow next to the run button on the editor and select Debug Python File in Terminal.
If you’re looking to debug a web application using Flask, Django or FastAPI, the Python extension provides dynamically created debug configurations based on your project structure under the Show all automatic debug configurations option, through the Run and Debug view.
But if you’re looking to debug other kinds of applications, you can start the debugger through the Run view by clicking on the Run and Debug button.
When no configuration has been set, you’ll be given a list of debugging options. Here, you can select the appropriate option to quickly debug your code.
Two common options are to use the Python File configuration to run the currently open Python file or to use the Attach using Process ID configuration to attach the debugger to a process that is already running.
For information about creating and using debugging configurations, see the Initialize configurations and Additional configurations sections. Once a configuration is added, it can be selected from the dropdown list and started using the Start Debugging button.
Command line debugging
The debugger can also be run from the command line. The debugger command line syntax is as follows:
As an example, from the command line, you could start the debugger using a specified port (5678) and script using the following syntax. This example assumes the script is long-running and omits the —wait-for-client flag, meaning that the script will not wait for the client to attach.
You would then use the following configuration to attach from the VS Code Python extension.
Note: Specifying host is optional for listen, by default 127.0.0.1 is used.
If you wanted to debug remote code or code running in a docker container, on the remote machine or container, you would need to modify the previous CLI command to specify a host.
The associated configuration file would then look as follows.
Note: Be aware that when you specify a host value other than 127.0.0.1 or localhost you are opening a port to allow access from any machine, which carries security risks. You should make sure that you’re taking appropriate security precautions, such as using SSH tunnels, when doing remote debugging.
|—listen or —connect||[ :]|
Debugging by attaching over a network connection
Local script debugging
There may be instances where you need to debug a Python script that’s invoked locally by another process. For example, you may be debugging a web server that runs different Python scripts for specific processing jobs. In such cases, you need to attach the VS Code debugger to the script once it’s been launched:
Run VS Code, open the folder or workspace containing the script, and create a launch.json for that workspace if one doesn’t exist already.
In the script code, add the following and save the file:
Open a terminal using Terminal: Create New Terminal, which activates the script’s selected environment.
In the terminal, install the debugpy package with python -m pip install —upgrade debugpy .
In the terminal, start Python with the script, for example, python3 myscript.py . You should see the «Waiting for debugger attach» message that’s included in the code, and the script halts at the debugpy.wait_for_client() call.
Switch to the Run and Debug view ( ⇧⌘D (Windows, Linux Ctrl+Shift+D ) ), select the appropriate configuration from the debugger dropdown list, and start the debugger.
The debugger should stop on the debugpy.breakpoint() call, from which point you can use the debugger normally. You also have the option of setting other breakpoints in the script code using the UI instead of using debugpy.breakpoint() .
Remote script debugging with SSH
Remote debugging allows you to step through a program locally within VS Code while it runs on a remote computer. It is not necessary to install VS Code on the remote computer. For added security, you may want or need to use a secure connection, such as SSH, to the remote computer when debugging.
Note: On Windows computers, you may need to install Windows 10 OpenSSH to have the ssh command.
The following steps outline the general process to set up an SSH tunnel. An SSH tunnel allows you to work on your local machine as if you were working directly on the remote in a more secure manner than if a port was opened for public access.
On the remote computer:
Enable port forwarding by opening the sshd_config config file (found under /etc/ssh/ on Linux and under %programfiles(x86)%/openssh/etc on Windows) and adding or modifying the following setting:
Note: The default for AllowTcpForwarding is yes, so you might not need to make a change.
If you had to add or modify AllowTcpForwarding , restart the SSH server. On Linux/macOS, run sudo service ssh restart ; on Windows, run services.msc , select OpenSSH or sshd in the list of services, and select Restart.
On the local computer:
Create an SSH tunnel by running ssh -2 -L sourceport:localhost:destinationport -i identityfile user@remoteaddress , using a selected port for destinationport and the appropriate username and the remote computer’s IP address in user@remoteaddress . For example, to use port 5678 on IP address 126.96.36.199, the command would be ssh -2 -L 5678:localhost:5678 -i identityfile firstname.lastname@example.org . You can specify the path to an identity file, using the -i flag.
Verify that you can see a prompt in the SSH session.
In your VS Code workspace, create a configuration for remote debugging in your launch.json file, setting the port to match the port used in the ssh command and the host to localhost . You use localhost here because you’ve set up the SSH tunnel.
Now that an SSH tunnel has been set up to the remote computer, you can begin your debugging.
Both computers: make sure that identical source code is available.
Both computers: install debugpy using python -m pip install —upgrade debugpy into your environment (while using a form of virtual environment is not required, it is a recommended best practice).
Remote computer: there are two ways to specify how to attach to the remote process.
In the source code, add the following lines, replacing address with the remote computer’s IP address and port number (IP address 188.8.131.52 is shown here for illustration only).
The IP address used in listen should be the remote computer’s private IP address. You can then launch the program normally, causing it to pause until the debugger attaches.
Launch the remote process through debugpy, for example:
This starts the package myproject using python3 , with the remote computer’s private IP address of 184.108.40.206 and listening on port 5678 (you can also start the remote Python process by specifying a file path instead of using -m , such as ./hello.py ).
Local computer: Only if you modified the source code on the remote computer as outlined above, then in the source code, add a commented-out copy of the same code added on the remote computer. Adding these lines makes sure that the source code on both computers matches line by line.
Local computer: switch to the Run and Debug view ( ⇧⌘D (Windows, Linux Ctrl+Shift+D ) ) in VS Code, select the Python: Attach configuration
Local computer: set a breakpoint in the code where you want to start debugging.
Local computer: start the VS Code debugger using the modified Python: Attach configuration and the Start Debugging button. VS Code should stop on your locally set breakpoints, allowing you to step through the code, examine variables, and perform all other debugging actions. Expressions that you enter in the Debug Console are run on the remote computer as well.
Text output to stdout, as from print statements, appears on both computers. Other outputs, such as graphical plots from a package like matplotlib, however, appear only on the remote computer.
During remote debugging, the debugging toolbar appears as below:
On this toolbar, the disconnect button ( ⇧F5 (Windows, Linux Shift+F5 ) ) stops the debugger and allows the remote program to run to completion. The restart button ( ⇧⌘F5 (Windows, Linux Ctrl+Shift+F5 ) ) restarts the debugger on the local computer but does not restart the remote program. Use the restart button only when you’ve already restarted the remote program and need to reattach the debugger.
Set configuration options
When you first create launch.json , there are two standard configurations that run the active file in the editor in either the integrated terminal (inside VS Code) or the external terminal (outside of VS Code):
The specific settings are described in the following sections. You can also add other settings, such as args , that aren’t included in the standard configurations.
Tip: It’s often helpful in a project to create a configuration that runs a specific startup file. For example, if you want to always launch startup.py with the arguments —port 1593 when you start the debugger, create a configuration entry as follows:
Provides the name for the debug configuration that appears in the VS Code dropdown list.
Identifies the type of debugger to use; leave this set to python for Python code.
Specifies the mode in which to start debugging:
- launch : start the debugger on the file specified in program
- attach : attach the debugger to an already running process. See Remote debugging for an example.
Provides the fully qualified path to the python program’s entry module (startup file). The value $
You can also rely on a relative path from the workspace root. For example, if the root is /Users/Me/Projects/PokemonGo-Bot then you can use the following example:
Provides the ability to specify the name of a module to be debugged, similarly to the -m argument when run at the command line. For more information, see Python.org
The full path that points to the Python interpreter to be used for debugging.
If not specified, this setting defaults to the interpreter selected for your workspace, which is equivalent to using the value $
Alternately, you can use a custom environment variable that’s defined on each platform to contain the full path to the Python interpreter to use, so that no other folder paths are needed.
If you need to pass arguments to the Python interpreter, you can use the pythonArgs property.
Specifies arguments to pass to the Python interpreter using the syntax «pythonArgs»: [«», «». ] .
Specifies arguments to pass to the Python program. Each element of the argument string that’s separated by a space should be contained within quotes, for example:
When set to true , breaks the debugger at the first line of the program being debugged. If omitted (the default) or set to false , the debugger runs the program to the first breakpoint.
Specifies how program output is displayed as long as the defaults for redirectOutput aren’t modified.
|Value||Where output is displayed|
|«internalConsole»||VS Code debug console. If redirectOutput is set to False, no output is displayed.|
|«integratedTerminal» (default)||VS Code Integrated Terminal. If redirectOutput is set to True, output is also displayed in the debug console.|
|«externalTerminal»||Separate console window. If redirectOutput is set to True, output is also displayed in the debug console.|
There is more than one way to configure the Run button, using the purpose option. Setting the option to debug-test , defines that the configuration should be used when debugging tests in VS Code. However, setting the option to debug-in-terminal , defines that the configuration should only be used when accessing the Run Python File button on the top-right of the editor (regardless of whether the Run Python File or Debug Python File options the button provides is used). Note: The purpose option can’t be used to start the debugger through F5 or Run > Start Debugging.
Allows for the automatic reload of the debugger when changes are made to code after the debugger execution has hit a breakpoint. To enable this feature set <"enable": true>as shown in the following code.
*Note: When the debugger performs a reload, code that runs on import might be executed again. To avoid this situation, try to only use imports, constants, and definitions in your module, placing all code into functions. Alternatively, you can also use if __name__==»__main__» checks.
Specifies whether to enable subprocess debugging. Defaults to false , set to true to enable. For more information, see multi-target debugging.
Specifies the current working directory for the debugger, which is the base folder for any relative paths used in code. If omitted, defaults to $
As an example, say $
|cwd||Relative path to data file|
|Omitted or $||data/salaries.csv|
When set to true (the default for internalConsole), causes the debugger to print all output from the program into the VS Code debug output window. If set to false (the default for integratedTerminal and externalTerminal), program output is not displayed in the debugger output window.
This option is typically disabled when using «console»: «integratedTerminal» or «console»: «externalTerminal» because there’s no need to duplicate the output in the debug console.
When omitted or set to true (the default), restricts debugging to user-written code only. Set to false to also enable debugging of standard library functions.
When set to true , activates debugging features specific to the Django web framework.
When set to true and used with «console»: «externalTerminal» , allows for debugging apps that require elevation. Using an external console is necessary to capture the password.
When set to true , ensures that a Pyramid app is launched with the necessary pserve command.
Sets optional environment variables for the debugger process beyond system environment variables, which the debugger always inherits. The values for these variables must be entered as strings.
Optional path to a file that contains environment variable definitions. See Configuring Python environments — environment variable definitions file.
If set to true , enables debugging of gevent monkey-patched code.
When set to true , activates debugging features specific to the Jinja templating framework.
Breakpoints and logpoints
The Python extension supports breakpoints and logpoints for debugging code. For a short walkthrough of basic debugging and using breakpoints, see Tutorial — Configure and run the debugger.
Breakpoints can also be set to trigger based on expressions, hit counts, or a combination of both. The Python extension supports hit counts that are integers, in addition to integers preceded by the ==, >, >=, >5 For more information, see conditional breakpoints in the main VS Code debugging article.
Invoking a breakpoint in code
In your Python code, you can call debugpy.breakpoint() at any point where you want to pause the debugger during a debugging session.
The Python extension automatically detects breakpoints that are set on non-executable lines, such as pass statements or the middle of a multiline statement. In such cases, running the debugger moves the breakpoint to the nearest valid line to ensure that code execution stops at that point.
Debugging specific app types
The configuration dropdown provides various different options for general app types:
|Attach||See Remote debugging in the previous section.|
|Django||Specifies «program»: «$ |
|Flask||See Flask debugging below.|
|Gevent||Adds «gevent»: true to the standard integrated terminal configuration.|
|Pyramid||Removes program , adds «args»: [«$ |
|Scrapy||Specifies «module»: «scrapy» and adds «args»: [«crawl», «specs», «-o», «bikes.json»] .|
|Watson||Specifies «program»: «$ |
Specific steps are also needed for remote debugging and Google App Engine. For details on debugging tests, see Testing.
To debug an app that requires administrator privileges, use «console»: «externalTerminal» and «sudo»: «True» .
As you can see, this configuration specifies «env»: <"FLASK_APP": "app.py">and «args»: [«run», «—no-debugger»] . The «module»: «flask» property is used instead of program . (You may see «FLASK_APP»: «$
The «jinja»: true setting also enables debugging for Flask’s default Jinja templating engine.
If you want to run Flask’s development server in development mode, use the following configuration:
There are many reasons why the debugger may not work. Sometimes the debug console reveals specific causes, but the main reasons are as follows:
The path to the python executable is incorrect: check the path of your selected interpreter by running the Python: Select Interpreter command and looking at the current value:
There are invalid expressions in the watch window: clear all expressions from the Watch window and restart the debugger.
If you’re working with a multi-threaded app that uses native thread APIs (such as the Win32 CreateThread function rather than the Python threading APIs), it’s presently necessary to include the following source code at the top of whichever file you want to debug:
If you are working with a Linux system, you may receive a «timed out» error message when trying to apply a debugger to any running process. To prevent this, you can temporarily run the following command: