Black is an auto-formatter for Python projects. It can be configured to automatically format your code when you save your files. This means you will spend less time formatting your code and have your code formatted in a clear and consistent way.

Black will format your code but it will not check it for errors. I recommend also installing linters such as flake8 and mypy.

When setting up Black for VScode, you will need to decide whether to install it globally or per-project. My personal preference is to set it up per project. This is so I can have full control of formatting and linting of each project. This is particularly important when you are working in a team with multiple developers, because you can ensure everyone is using the same version, and ensure consistency between environments.

I am going to show you how to install Black in a VScode environment. Once installed, we will configure VScode to automatically format your files on save.

Prerequisites

You will need a Python or Django project with an active virtual environment. Your project should be open in VScode.

Install the Python VScode extension

VScode has an extension called “Python” (docs). This is a free extension that adds support for the Python programming language in VScode. You will need this for error checking, syntax highlighting, and auto-formatting.

Find this extension and install it. You may need to reload VScode afterwards, for the change to take effect.

Important! Make sure your Python interpreter uses your virtual environment

You need to make sure the Python interpreter of VScode uses the same version of Python as your virtual environment.

By using the Python interpreter of your virtual environment, VScode can tell what packages are installed. If we install Black but our interpreter is incorrect, VScode will not think Black is installed.

How to select your Python interpreter

Start by opening the command palette. To do this, select “View” from the top menu and then select “Command Palette”.

Alternatively, use CTRL+SHIFT+P on Windows and Linux, or CMD+SHIFT+P on Mac.

In the Command Palette, type “Python: Select Interpreter”. Select the option of that name from the dropdown.

VScode is then going to give you a list of options. You need to pick the one that has the same path as your virtual environment.

Your virtual environment may already appear as the recommended interpreter.

If it doesn’t, don’t worry. Select “Enter Interpreter Path” instead.

This will bring up a window for you to select an interpreter. Look for a file called “python3” or similar in the “bin” directory of your virtual environment.

Step 1: Install Black

Install Black by running the following command in your terminal:

pip install black

Step 2: Create a settings.json file

We need somewhere to store settings that are just for our project.

When you change settings in VScode, it may create a settings.json file for you.

If you don’t have a directory called .vscode, you can create one.

Go to the root directory and create a sub-directory called .vscode. Inside this folder, create a file called settings.json.

Step 3: Set black as the formatting provider

Now that we have a file to store settings for our project, we need to instruct VScode to use Black.

In settings.json, we can add a setting to define Black as the formatting provider.

# .vscode/settings.json

{
    "python.formatting.provider": "black",
}

Step 4: Set VScode to format files on save

The final step is to add a setting that will instruct VScode to format files when they are saved.

# .vscode/settings.json

{
    "python.formatting.provider": "black",
    "editor.formatOnSave": true
}

Conclusion

Black is a code formatter that can be configured to automatically format files when they are saved.

Setting up Black is a combination of installing the Black package and configuring VScode to use it.

The instructions in this tutorial involve setting up Black at a project-level, not globally. If you want to install Black globally, then I recommend using the Black VScode extension.

Taking the time to set up Black will lead to less time spent formatting your code, and ensure consistency throughout your project.