Setting Up Python Development Environments with Visual Studio Code

[Updated: January 3, 2021]

Visual Studio Code (VS Code) has been my favorite editor for a few years. With the activity enhancement made by Microsoft and the community, VS Code has numerous extensions to satisfy different development needs. With the remote development extension, I can now use the VS Code for my daily work and open source projects in all environments. This article is a brief tutorial of the VS Code setup for Python developments — the setup I use daily. Hopefully, this tutorial could help people who want to use the VS Code for Python development. Besides, VS Code has tremendous documents. Visit https://code.visualstudio.com/docs for more details.

Plot

This tutorial uses a simple Python project to demonstrates the VS Code setup for Python development on Windows 10, Windows Subsystem for Linux, remote Linux, and Raspbian on Raspberry Pi.

The Python project has the following layout:

project
  |---- mathlib
  |           |---- __init__.py
  |           |---- compute.py
  |---- test_compute.py

And the contents of compute.py and test_compute.py are:

compute.py

def inc(value: int) -> int:
    """Return the number increased by one."""
    return value + 1

def dec(value: int) -> int:
    """Return the number decreased by one."""
    return value - 1

test_compute.py

from mathlib import compute

def test_int():
    assert compute.inc(value=5) == 6

def test_dec():
    assert compute.dec(value=5) == 4

Windows-Centralized Setup

Although VS Code can run on different platforms, e.g., Linux and macOS, this tutorial uses Windows 10 as the central place to run VS Code.

Assumptions and Requirements

The software used in this tutorial are:

• Visual Studio Code 1.52 with extensions: Python 2020.12, Remote Development 0.20.0, Pylance 2020.12.2
• Python 3.9
• Windows 10 2004
• Ubuntu 20.04 (for WSL and remote Linux)
• Raspbian on Raspberry Pi 3 B+

A typical Python development includes the virtual environment, linting, test, and debug. This tutorial uses:

• venv for creating a virtual environment
• pytest for unit testing
• flake8 for lining
• mypy for type checking
• pydocstyle for document style checking
• black for code style checking

The Python extension supports all of the linters above. More details for linting https://code.visualstudio.com/docs/python/linting.

Installation on Windows

Since Windows 10 is the host VS Code runs in this tutorial, we need to install VS Code on the Windows host.

Install VS Code

1. Download the VS Code from https://code.visualstudio.com/. When the tutorial is written, the latest version is 1.52.
2. Double click the downloaded binary, VSCodeUserSetup-x64-1.52.1.exe, to install.

Install VS Code Extensions

VS Code has thousands of thousand extensions; the Python and Remote Development extensions are the minima for Python development on Windows and remote platforms. Pylance is optional but highly recommended, which provides fast and feature-rich language support for Python.

• Launch VS Code.
• Click the extension icon

or type Ctrl+Shift+X to open the extension windows.

• On the search bar, type Python and install it.
• On the search bar, type Remote Development and install it. Remote Development extension also installs Remote — Containers, Remote — SSH, Remote — SSH: Editing Configuration Files, and Remote — WSL.

After the installation, VS Code should look like this:

Synchronize VS Code Setting

Since VS Code 1.48, the Settings Sync feature is available in the stable release. The feature allows us to sync our VS Code settings such as configurations, extensions, and keybindings across all of our machines. It is handy when we have multiple devices. Highly recommended to enable it. See the official documents here: https://code.visualstudio.com/docs/editor/settings-sync

Setup Python Development Environment on Windows

To run Python code on Windows, we need to install Python

Install Python

We can install Python by 1. Microsoft Store, or 2. Python official website. Follow the instructions to install it. The latest stable version is 3.9 when this article is written.

Create a Virtual Environment

Assume we use C:\workspace as the workspace for this tutorial, and working_environment is our virtual environment. Use Command Prompt to issue the following commands:

C:\Users\user> cd C:\workspace
C:\Users\user> python3.9 -m venv working_environment

Create the Project and Setup VS Code

Now we are ready to create the project with VS Code.

• Create a new folder called project under C:\workspace\
• Launch the VS Code
• File -> Open Folder
• Open the project folder
• Add folder and files shown at Plot section, so it looks like

Once we add a Python file, VS Code automatically detects the Python environment; by default, it picks the system default Python interpreter.

It may also detect something is not installed, e.g., pylint and pytest.

Ignore them for now since we do not want to install these to the system Python interpreter.

• We want to use the virtual environment, working_environment, we just created for this project. To do so, we need to tell VS Code the path to the virtual environment.
• File -> Preferences -> Settings
• Type venv path at the top search bar, and the configure option will show up
• Add C:\workspace like the picture shows below

• Click the Python Interpreter icon to select the working_environment. working_environment should be available now. If it does not show up, relaunch the VS Code.
• Click the icon and choose working_environment

• Once we set up the virtual environment, we can install the missing components that VS Code detects (e.g., pytest) if the VS Code bumps up the suggestion window.

(To learn more about Python virtual environments, please check https://code.visualstudio.com/docs/python/environments)

Configure Linting, Type Checking, and more

VS Code enabled a few linters, such as pylint, by default. It also allows us to customize our linting configurations. This section uses flake8 as an example to demonstrates the customization.

• File -> Preferences -> Settings and type linting at the top search bar. Flake8 options will show up.

• Enable and install flake8.
• Check the box of flake8 option.

• As soon as we check the box, an install option will pop up. Click it to install flake8. If the window does not show up, reload the VS Code.

• If we want to add non-default options flake8, click the Add Item button.

• Add the argument we want. For example, if we prefer to set the max line length to 88, we can do the following.

Repeat the same steps to configure other linters such as mypy, black, and pydocstyle.

To learn more about the linting configurations, please refer to the VS Code document: https://code.visualstudio.com/docs/python/linting.

Testing and Debugging

For the setups of testing and debugging, VS Code has very comprehensive documents.

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

Now, we should have a working environment for our Python projects with VS Code.

Setup Python Development Environment on Linux via SSH

The VS Code Remote — SSH extension allows us to open a remote folder on a remote machine with a running SSH server and take full advantage of VS Code, such as auto-completion, debugging, and linting.

Assumption: This section assumes that we have a remote Linux (Ubuntu 20.04) with SSH enabled.

Step 1: Install OpenSSH client on the Windows 10 Host

To install OpenSSH, do the following:

Settings -> Apps -> Apps & features -> Optional features -> Optional features -> Add a feature

Find OpenSSH client and click ‘’Install’’. After the installation completes, it should look like this:

More options for OpenSSH can be found at https://docs.microsoft.com/en-us/windows-server/administration/openssh/openssh_install_firstuse.

Step 2: Setup the SSH Key

On the Windows 10 host, launch Command Prompt and do the following steps:

• Generate an SSH key pair. And accept all the default values.

C:\Users\user> ssh-keygen -t rsa -b 4096

Add the contents of the local public key (the id_rsa.pub) to the appropriate authorized_keys file on the SSH host, i.e., the remote Linux).

C:\Users\user> SET REMOTEHOST=your-user-name-on-host@host-fqdn-or-ip-goes-here

Copy the local public key to the remote Linux.

C:\Users\user> scp %USERPROFILE%\.ssh\id_rsa.pub %REMOTEHOST%:~/tmp.pub
C:\Users\user> ssh %REMOTEHOST% "mkdir -p ~/.ssh && chmod 700 ~/.ssh && cat ~/tmp.pub >> ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys && rm -f ~/tmp.pub"

Step 3: Connect to the Remote Linux Host

• Launch VS Code on Windows 10
• Click the remote development icon

and select SSH Targets to add an SSH host.

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

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

• We can also open the config file to check its detail and modify it. The config may look like

• Click the connect icon (in this example, its name is remote-ubuntu) to connect to the remote machine.

• A new window will open and ask the user to choose the remote platform and enter the password. Choose Linux as the remote platform and enter the password.

• Once the connection establishes, the icon

will appear.

• Install Python extension on the remote Linux. The Python extension has been installed on the Windows host but not in the remote Linux. To provide all Python features that VS Code provides, we need to install the Python extension on the remote Linux.
• Click the extension icon

. It should show something like the picture below

The top section indicates the extensions installed on the local machine, i.e., Windows 10, in this example. The bottom section shows the extensions installed on the remote machine, i.e., Ubuntu 20.04 in this case. Now the remote machine does not have any extension installed.

• Click the Install in SSH button to install the Python extension on the remote machine.

• Once the installation completes, the extension window becomes

Step 4: Setup the Project

On the remote Linux

Now, we can create a virtual environment and a Python project on the remote Linux.

• SSH to the remote Linux machine.
• Create a workspace folder

$ mkdir workspace
$ cd workspace/ 

• Create a virtual environment, working_environment

$ python3.9 -m venv working_environment

• Create a project folder

$ mkdir project

On the Windows Host

• If we try to open a folder by File -> Open Folder, it will show the remote Linux filesystem. Select the project folder created above.

Repeat the steps mentioned in the section: Create the Project and Setup VS Code. Note: the settings we changed for Windows are per user. Here, we should change the settings for Remote.

Now, VS Code should be ready for Python development on the remote Linux machine.

Check the remote development documents at https://code.visualstudio.com/docs/remote/ssh.

Setup Python Development Environment on Raspberry Pi via SSH

Since early 2020, VS Code officially supports ARM architectures. Therefore, we can set up the remote development on Raspberry Pi in the same as regular remote Linux.

Follow the steps mentioned at Setup Python Development Environment on Linux via SSH. The steps are the same. The only difference is that the remote Linux machine becomes Raspbian on Raspberry Pi.

Setup Python Development Environment with WSL

The Windows Subsystem for Linux brings developers 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.

Step 1: Enable and Install WSL

Follow the instructions to enable and install WSL: https://docs.microsoft.com/en-us/windows/wsl/install-win10

Step 2: Create a Virtual Environment and the Project

From the WSL command line, issue the following commands:

• Create a workspace.

$ mkdir workspace
$ cd workspace

• Create a virtual environment, working_environment.

$ python3.9 -m venv working_environment

• Create a project folder.

$ mkdir project

Step 3: Connect to WSL from VS Code

• Launch VS Code.
• Click the remote development icon

and select WSL Targets to add a WSL target.

Or type Ctrl+Shift+P to start Command Palette and type Remote-WSL: New Window

• After select Remote-WSL: New Window, a new VS Code window will show up and connect to the WSL. On the left bottom, this icon

indicates VS Code has connected to the WSL.

• Same as Remote SSH, we need to install the Python-related extension on the WSL. Click the button to install.

Step 4: Setup the Project

Once the VS Code connects to the WSL, we can set up the Python project in the same way we did for the Windows and remote Linux projects.

• Open the project folder.

• Repeat the steps mentioned in the section: Create the Project and Setup VS Code. Note: same as Remote SSH, for WSL, we should change the settings under Remote [WSL: Ubuntu].

Now, VS Code should be ready for Python development with the WSL.

More details of remote develop with WSL can be found at https://code.visualstudio.com/docs/remote/wsl.

Conclusion

VS Code is highly extensible and configurable through extensions and settings, so developers can add features via extensions and configure VS Code to enhance our workflow. In addition to Python and Remote Development extensions, here is the list of extensions I think useful and use daily.

• Bookmarks help navigate the code.
• Bracket Pair Colorizer highlights matching brackets.
• Code Spell Checker checks the spelling of the source code.
• GitLens provides seamlessly navigate and explore Git repositories.
• Visual Studio IntelliCode provides AI-assisted development features for Python.

Although this tutorial uses Windows 10 as the host for VS Code, VS Code can be installed and run on Linux and Mac. We can apply the setup described in the article to Linux and Mac. Hopefully, you found this article useful.

Originally published at https://formosa1544.com on September 4, 2019.