[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.424452561
- 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
- Download the VS Code from https://code.visualstudio.com/. When the tutorial is written, the latest version is 1.52.
- 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
underC:\workspace\
- Launch the VS Code
- File -> Open Folder
- Open the project folder
- Add folder and files shown at Plot, 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
- 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.
- Check the box of
- 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 appropriateauthorized_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 likeC:\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.
1 thought on “Setting Up Python Development Environments with Visual Studio Code”