Skip to main content

Black - Auto-Format Your Python Code Like a Pro

· 3 min read
Serhii Hrekov
Serhii Hrekov
software engineer, creator, artist, programmer, projects founder

Writing clean and consistent code is a mark of professionalism, and it also makes collaboration easier. But keeping formatting consistent manually is hard. That’s where Black, the Python code formatter, shines.

Black automatically formats your code according to PEP 8 (Python’s style guide), with minimal configuration and zero fuss. This guide will show you how to install it, use it, and why it's helpful — especially if you're new to Python programming.

Why Use Black?​

  • ✅ Enforces consistent code style across your project
  • ✅ Saves time during code reviews and pull requests
  • ✅ Reduces bike-shedding about tabs, spaces, line breaks, etc.
  • ✅ Works out-of-the-box, no config needed
  • ✅ Widely adopted by the Python community and open-source projects
  • It's a part of Shift Left paradigm that we talk about in this article

Installing Black​

You can install Black using pip:

pip install black

Or install it with pipx (recommended):

pipx install black

Basic Usage​

Once installed, simply run it on a file or a folder:

black your_script.py

To recursively format an entire project:

black .

Black will reformat the file(s) and show you what was changed.

Example: Before and After Black​

Original Code (before)​

def add(a,b): return a+b
print(add(1,2))

After Running black your_script.py​

def add(a, b):
    return a + b


print(add(1, 2))

Much more readable, right?

Formatting In-Place vs Checking​

To check if any file would be reformatted without actually changing it:

black --check .

This is useful in CI pipelines to enforce formatting rules without modifying the code.

Integrate with VS Code​

  1. Install the “Python” extension from Microsoft.

  2. Set Black as your default formatter:

    // settings.json
    "python.formatting.provider": "black",
    "editor.formatOnSave": true

Now, every time you save a file, Black formats it automatically!

When Black Won’t Change Your Code​

Black won’t change the logic of your code — only its appearance. If it already meets the style guidelines, it may remain unchanged. This makes it safe to use in production projects.

Optional Configuration​

Black supports a few optional flags:

black --line-length 100 .

You can also create a pyproject.toml file:

[tool.black]
line-length = 100
target-version = ['py311']
skip-string-normalization = true

Best Practices​

  • Use Black early in your project to maintain consistency.

  • Combine with linters like flake8 or ruff for full style + logic linting.

  • Add it to your pre-commit hook:

    pip install pre-commit
    pre-commit install

    Then add this to .pre-commit-config.yaml:

    - repo: https://github.com/psf/black
      rev: stable
      hooks:
        - id: black

Further Reading​

Summary​

Black is the uncompromising code formatter — and that's a good thing. As a beginner, using tools like Black helps you focus more on learning logic, structures, and patterns — not wasting time on line breaks or indentation rules.

Install it, run it, and let Black worry about your formatting.

Happy coding!