In this post we'll look at how to develop in Python using Visual Studio Code. I'll also show you a few extensions that can make your life much easier while working with Python!

Initial setup

When you install Python (which I recommend you do via the official installer), remember in which folder you installed it. And on Windows, make sure to tick the "Add Python to PATH" in the first screen of the official installer.

Download Visual Studio Code and install it like you would any other application.

Open Visual Studio Code and navigate to the Extensions panel on the left hand side. There, look for the Python extension and install it:

Visual Studio Code window with the Extensions section open, and the Python extension selected

Once that's installed, you can open any folder using Visual Studio Code and create a file that ends in .py. The Python extension gives you syntax highlighting and also helps you code by offering suggestions and hints.

Visual Studio Code with a Python file opening, showing the Python version at the bottom right

You can change which version of Python the extension uses by clicking on the bottom right, where in the screenshot it says "Python 3.10.0".

After you create a virtual environment, which you should always do for each Python project you work on, you can choose it as the Python interpreter by clicking on the "Python 3.10.0" button.

Our article, "Working with virtual environments: the complete guide", will help you learn how to use virtual environments if you aren't familiar with them yet.

Here's a link to the Python extension: https://marketplace.visualstudio.com/items?itemName=ms-python.python.

Linting, formatting, and sorting imports with VSCode

Linting with Ruff in Visual Studio Code

A linter is a tool that checks your code for common issues, and warns you if it finds any. There are many linters in the Python ecosystem, but lately I've been favouring Ruff. It's fast and extensible.

The easiest way to get it to work in Visual Studio Code is to install the Ruff extension. Here's a link to the ruff repository and the extension repository in case you want to read up on it further.

Formatting with Black in Visual Studio Code

I like the black formatter for Python because it has sane defaults, which means you don't have to configure it at all. Just install it, tell VSCode to run it, and you're good to go.

To install black, make sure you've created a Python virtual environment and you've selected it in VSCode as your interpreter.

Then, install it using the console (make sure the console has the virtual environment activated too):

pip install black

Next, open your VSCode settings (with CMD+, or CTRL+,), and find the "Python Formatting Provider" setting. Set it to black:

Screenshot showing three steps to find the formatting provider setting. First type 'formatting' in the search. Then choose 'Python' from the left hand dropdown. Finally change the 'Python Formatting Provider' dropdown to 'black'

Import sorting with isort in Visual Studio Code

Sorting your imports may sound like a completely useless thing to do, but we do it for consistency. It's especially useful if you are working on a codebase with other people.

Sorting the imports means that when you import a built-in library (e.g. os), that goes at the top. Then, go third-party libraries, like flask. Finally go imports from your own codebase. Within each of these three segments, it sorts imports alphabetically.

This makes it a bit easier to find the import you're looking for, if you have many of them.

When you installed the Python extension for VSCode, you also unwittingly installed the isort extension which handles sorting imports. All you have to do is run it.

You can run isort by opening the command palette (CMD+SHIFT+P or CTRL+SHIFT+P), then typing "Python Refactor: Sort Imports".

Sorting imports and formatting on save with VSCode

To enable formatting and import-sorting on save, open your VSCode settings, and then open them in JSON format using this button:

Screenshot showing how to open the VSCode settings in JSON format, with a circle surrounding a button that looks like a file with an arrow on the top right of the screen

In there, make sure these settings are there (careful to not have duplicate settings, though):

{
    "[python]": {
        "editor.codeActionsOnSave": {
            "source.organizeImports": true,
            "source.fixAll": true
        }
    },
    "ruff.organizeImports": false,
    "editor.formatOnSave": true,
    "python.formatting.provider": "black"
}

The last setting should already be there, since you selected Black as the formatter earlier on, but the others may be new.

Here's what each of the keys mean:

  • [python]: the following settings only apply to the Python language.
  • editor.codeActionsOnSave: the following settings define actions that the editor will run when a file is saved.
  • source.organizeImports: tell the editor to sort imports on save.
  • source.fixAll: tell the editor to use the linter to fix all issues it can (those it can't fix are just left as warnings).
  • ruff.organizeImports: setting this to false means we'll use isort instead of ruff for sorting imports.
  • editor.formatOnSave: use Black to format the code when we save the file.
  • python.formatting.provider: which formatter to use.

Now whenever you save a file, isort will sort your imports, ruff will try to fix what it can (and warn you about what it can't fix), and then black will format the code.

Text flickering when you save?

By default, when you sort your imports with isort, you end up with something like this:

from module import (abc1, abc2, abc3,
                    abc4, abc5, abc6)

But if you format your code with Black, it will change the imports to this:

from module import (
    abc1,
    abc2,
    abc3,
    abc4,
    abc5,
    abc6,
)

Since isort processes the file first, and then Black processes the result, you may see text flicker while for a few milliseconds the file is saved in the first format.

To fix this, we should tell isort to use the same format as Black. That way, the text won't flicker.

Create a new file in your Python project root called pyproject.toml. This file is used for Python configuration, and it is compatible with most Python tooling (including isort and black).

Inside the file, add this:

[tool.isort]
profile = "black"

Then, tell VSCode to restart the isort formatting server by launching the command palette (CMD+SHIFT+P or CTRL+SHIFT+P) and then typing "isort Formatter: Restart Server".

Now when you save, the text won't flicker anymore!

The indent-rainbow extension

An extension called "indent-rainbow" will color every indentation level in Python in a slightly different color, so you can easily tell which parts of your code are at which indentation level.

This is what the extension will do:

Python code where each level of indentation has the tab character coloured in with a slightly different light colour

Link: https://marketplace.visualstudio.com/items?itemName=oderwat.indent-rainbow

The Rainbow Brackets extension

If you like the indent-rainbow extension, you might also like Rainbow Brackets extension, which highlights nested parentheses, square brackets, and curly braces in different colours, making it easier to keep track of nested brackets.

Link: https://marketplace.visualstudio.com/items?itemName=2gua.rainbow-brackets#overview

The vscode-icons extension

While this extension is by no means required to run Python code, it change the icons displayed beside files and folders in the sidebar. I find this makes them easier to scan!

Link: https://marketplace.visualstudio.com/items?itemName=vscode-icons-team.vscode-icons

The LiveShare extension

VSCode has a great extension for collaborating with others. It lets you share your whole VSCode workspace so that others can join it and code with you. I often use it for pair programming, although it's great for asking for getting help as well!

Download and install the LiveShare extension here: https://marketplace.visualstudio.com/items?itemName=MS-vsliveshare.vsliveshare

After you've installed it, you'll see a "Live Share" icon and text at the bottom of your VSCode window. Pressing that will start a Live Share session and give you a link that you can share with whomever you want joining your shared session.

Conclusion

That's it! As long as your Python version is in your PATH (which happens automatically on Mac and Linux, and you must tick the box in the installer in Windows), the Python extension will straight work out of the box!

If you have any issues, Google is your best friend as tens of thousands of people use these extensions, so you're likely to be able to find a solution. The development team is also helpful in their GitHub page.

The GitHub page also contains extensive guides and information on how to get the extension up and running, it case it's necessary!

Hope this has been helpful and your environment is now all set up. Happy coding!

Changelog

  • March 2023: Removed the "Code Runner" extension as I've found myself not using it at all. Added linting, formatting, and import sorting.