Skip to main content
  1. Posts/

Black Formatter Setup for Python Project

··371 words·2 mins·
Table of Contents

This post is about how to set up black, the popular code formatter for Python projects.

Basic usage

Format the file inplace :


If we only want to check if the file needs reformat, we can use --check:

black --check

Show the diffs between old and new file if black were to reformat:

black --diff --color

skip formatting for some code

To skip formatting for a single line, you can add # fmt: skip at the end of the line. To skip formatting for a block of code, you need to add # fmt: off and # fmt:on before and after the block.


Black offers very little configuration. You can put the configuration inside pyproject.toml under the section []:

# The keys are the long option names what black accept on the command line.
line-length = 100
skip-string-normalization = true

The pyproject.toml file should be put at the root of the project.


Integration to Editor/IDE


For latest version of PyCharm, open settings, and go to Tools --> Black, you can configure how black should be run for a file.

Visual Studio Code

Install the black formatter extension from Microsoft. Open the command plate (shift + command + P), and search Open User Settings (JSON), and open the user setting. Add the following config:

    "[python]": {
        "editor.defaultFormatter": "",
        "editor.formatOnSave": true,


For neovim you can use dedicated formatter plugins from here.

You can also use python-language-server and black as the formatter. The detailed configuration can be found here.

CI/CD integration

GitHub action

For GitHub action integration, please check the official doc:

Azure DevOps

For Azure DevOps, we can add a custom step to check the code formatting:

- script: |
    pip install black
    black --check --diff .    
  displayName: Check code format with black


Ignore the code reformat commit

Create a file named .git-blame-ignore-revs in the project root and add the commit that reformat the code:

# reformat the code using black

Then when using git blame, we can provide this to ignore certain commit:

git blame --ignore-revs-file .git-blame-ignore-revs



Configure Python logging with dictConfig
··503 words·3 mins
Using Virutal Environment in Python with venv
·254 words·2 mins
FastAPI testing and OpenAPI doc generation
··239 words·2 mins