[Updated: April 24, 2025]

Visual Studio Code (VS Code) has been my favorite editor for many years. With the active enhancements made by Microsoft and the community, VS Code has numerous extensions to satisfy various development styles. Among all VS Code’s features, the most powerful one to me is the Remote Development, which allows me to open any folder anywhere, including Windows Subsystem for Linux (WSL), and any remote machines, even a Raspberry Pi, and take advantage of VS Code’s full features to edit the code from my Windows machine. The ability to do remote programming makes VS Code an excellent choice for cross-platform languages like Python. This article demonstrates how I set up VS Code for Python programming on multiple platforms. I hope it can be a reference for people who want to use VS Code for Python programming in multiple environments.

Overview

This tutorial assumes Windows is the host on which VS Code is installed and used to open a project on various platforms.

Although this guide installs VS Code on Windows, it can be installed on any supported platform and can still access remote folders on any machine.

Remote Development Extension

The key to making remote development possible is the Remote Development extension pack. This pack supports remote SSH, tunnels, containers, and WSL, which covers almost all possible remote use cases.

Python Specific Tools

For Python programming, a typical development environment includes the following.

• venv for creating a virtual environment
• flake8 for linting
• mypy for type checking
• pydocstyle for document style checking
• black for coding style checking and formatting
• pytest for unit testing

Notes

This tutorial uses the following software versions:

• Visual Studio Code 1.99.3
• Windows 11 24H2
• WSL 2
• Raspberry Pi 3 B+

Windows Setup

Since VS Code runs on Windows in this tutorial, the first step is to install VS Code and configure the Python environment on Windows.

Install VS Code

Download VS Code from https://code.visualstudio.com/, and follow the instructions to install it.

Install Extensions

To install extensions, after launching VS Code, click the extension icon  or type Ctrl + Shift + X to open the extension window and install the following extensions.

• Python. The extension also includes some common extensions for Python programming, such as Pylance.
• Remote Development.  The extension pack contains Remote – SSH, Remote – Tunnels, Dev Containers, and WSL extensions.
• Flake8 for linting.
• Mypy Type Checker for type checking.
• Black Formatter for code formatting.

Python Environment

A typical Python workflow includes the following steps.

1. Install Python.
2. Set up a virtual environment.
3. Start writing the code.

Install Python

On Windows, Python can be installed via 1. Microsoft Store, or 2. The Python official website. Follow the instructions to install it.

Create a Virtual Environment

Assuming C:\Users\user\workspace is the work directory, and C:\Users\user\.venv is the folder for virtual environments. Use PowerShell to run the following commands and create a virtual environment called myenv:

PS C:\Users\user>mkdir workspace
PS C:\Users\user>mkdir .venv
PS C:\Users\user>python -m venv .venv\myenv

Set Up VS Code

This tutorial uses the python-template project as an example to demonstrate the setup.

• Clone the python-template project under C:\Users\user\workspace\
• Launch VS Code
• File -> Open Folder
• Open the python-template folder
• Once a Python file is selected, VS Code automatically detects the Python environment and picks up the system default Python interpreter.

• Configure VS Code to use the virtual environment, myenv, that we created for this project.
  • File -> Preferences -> Settings
  • Type venv in the top search bar, and the configure option will appear
  • Add ~/.venv like the picture shows below. ~\.venv works too; VS Code automatically adjusts the path operator (i.e., \ or /) based on the operating system accordingly. Since this tutorial also includes WSL and Linux, use / for consistency.

Note that settings can be set in the User scope or Workspace scope. Since the tutorial leverages the ability of remote development, the Venv Path is set in the User scope so that the setting can be reused in WSL or other environments.

• Press Ctrl + Shift + P, type Python: Select Interpreter, and select myenv.

• Once the virtual environment is selected, the icon will become the Python interpreter we chose.

(Check here to learn more about Python virtual environments.)

Configure VS Code’s Linting Options

The python-template includes linting configurations, such as .flake8 and .mypy.ini, so the linting extensions use those rules automatically. By default, they use the root directory of the workspace ${workspaceFolder}. The following picture shows the flake8 settings as an example.

If configuring a linting setting tied to VS Code is desired, whether in the user or workspace scope, the option can be added to those extensions’ settings via the Add Item button shown in the picture above.

Please check the extensions’ documents for more details on their settings, and Linting and Type Checking for the configurations used in the python-template example.

Testing and Debugging

Regarding the testing and debugging setups, VS Code has very comprehensive documentation.

• Testing: https://code.visualstudio.com/docs/python/testing
• Debugging: https://code.visualstudio.com/docs/python/debugging

VS Code is ready for Python programming on Windows.

Windows Subsystem for Linux Setup

The Windows Subsystem for Linux allows developers to access the Linux environment directly on Windows without using a virtual machine. With the Remote Development extension, we can enjoy VS Code’s full features and develop, run, and debug Linux-based applications on Windows.

Enable and Install WSL

Follow the instructions to enable and install WSL: How to install Linux on Windows with WSL.

Note that older Windows versions need extra steps to configure WSL. See Manual installation steps for older versions of WSL.

Create a Virtual Environment and the Project

From the WSL command line, run the following commands to create a workspace folder, create a virtual environment, and clone the python-template sample.

• Create a workspace folder.

$ mkdir workspace

• Create a virtual environment.

$ python -m venv ~/.venv/myenv

Note that the python command may vary depending on the Linux distribution. For example, it could be python3 or python3.12. Adjust the command accordingly.

• Clone the python-template sample.

$ cd workspace 
$ git clone https://github.com/burpeesDaily/python-template.git

Connect to WSL from VS Code

• Launch VS Code.
• Click the remote development icon  and select the WSL target (Ubuntu in this example) to open a new window.

Or press Ctrl + Shift + P to start Command Palette and type WSL to connect to WSL or open a folder in WSL.

• After VS Code connects to WSL, click the extension icon and install the Python-related extensions or any extensions that will run on WSL in WSL.

The extensions have been installed on Windows but not on WSL. They need to be installed on WSL to work.

Set up the Project

• File -> Open Folder
• Open the python-template folder located at ~/workspace/. After VS Code connects to WSL, it can open the filesystem in WSL.
• Since we have set the virtual environment path to ~/.venv in the User scope, the myenv virtual environment will be detected automatically. So, we can press Ctrl + Shift + P, type Python: Select Interpreter, and select myenv.

• Settings configured in the User scope automatically take effect in WSL. However, settings can also be configured in the WSL scope if desired.

VS Code is now ready for Python programming in WSL.

More details of remote development with WSL can be found at Developing in WSL.

Remote SSH Setup

The Remote – SSH extension allows us to use any remote machine, including IoT devices like Raspberry Pi, with an SSH server as our development environment. No source code needs to be on our local machine; the extension runs commands and other extensions directly on the remote machine.

This section uses a Raspberry Pi as an example to demonstrate the remote SSH setup.

Assume the Raspberry Pi already has a virtual environment at ~/.venv/myenv and the python-template project located at ~/workspace.

Connect to the Remote Machine

• Launch VS Code on Windows.
• Click the remote development icon  and select SSH to add an SSH host.

Or press Ctrl + Shift + P to start Command Palette, type Remote-SSH, and select Remote-SSH: Add New SSH Host ….

• Follow the instructions to add the remote host and choose the appropriate config file to store, which may look like C:\Users\user\.ssh\config.

• The config file can also be opened to check its details and to be modified. The config may look like

• Click the connect icon (raspberry-pi in this example) to connect to the remote machine.

• Once it connects to the remote machine, it will ask the user to choose the remote platform and enter the password. Choose Linux as the remote platform and enter the password.
• After VS Code successfully connects to the remote machine, we can install the extensions on it, similar to the WSL setup in the previous section.

Set up the Project

• After VS Code connects to the remote machine, we open the python-template folder at ~/workspace/ and select myenv as the virtual environment.
• Settings configured in the User scope are automatically applied to the remote SSH environment. However, settings can also be configured in the remote scope if desired.

VS Code is now ready for Python programming on the Raspberry Pi. Although this section uses the Raspberry Pi as an example, the remote machine can be almost anything, such as Linux, Mac, or Windows.

More details of remote development with WSL can be found at Remote Development using SSH.

Recommendations

VS Code is highly extensible and configurable through extensions and settings, so developers can add features via extensions and configure VS Code to enhance the workflow. Even better, extensions and settings can be synced via Settings Sync, so we don’t need to configure VS Code every time we use a new machine. The list below includes the extensions used in this tutorial and my recommendations.

• Python. The extension also includes some common extensions for Python programming, such as Pylance.
• Remote Development.  The extension pack contains Remote – SSH, Remote – Tunnels, Dev Containers, and WSL extensions.
• Flake8 for linting.
• Mypy Type Checker for type checking.
• Black Formatter for code formatting.
• Code Spell Checker checks the spelling of the source code.
• GitLens provides a seamless way to navigate and explore Git repositories.
• GitHub Copilot. An AI Assistant.