Repolode
Submit
psf

psf/black

Black is an opinionated, deterministic Python code formatter that rewrites files in place with minimal diffs.

View on GitHubWebsite
Stars
41,948
Forks
2,940
Open issues
298
Last commit
13 hours ago

What is it?

Black is an opinionated Python code formatter. It reformats entire files in place, with a deliberately small set of style options, so that code looks the same across projects and formatting debates are avoided. It is designed to produce the smallest possible diffs, which keeps code reviews focused on content.

Black requires Python 3.10 or newer and installs with pip. It can also format Jupyter Notebooks when installed with the jupyter extra, and standalone executables are available for users who do not want a Python installation. Configuration is read from pyproject.toml, including include and exclude patterns, though the defaults are intended to work without changes.

As a safety measure, Black checks that reformatted code still parses to an AST equivalent to the original, and a --fast flag skips this check. The project documents its code style and a stability policy that limits style changes to bug fixes and support for new Python syntax.

Key features

  • 01Reformats Python files in place with a small, fixed set of style options.
  • 02Produces minimal diffs to keep code reviews focused.
  • 03Verifies that formatted code is AST-equivalent to the original by default.
  • 04Formats Jupyter Notebooks when installed with the jupyter extra.
  • 05Reads project settings from pyproject.toml.

Use cases

  • Enforcing one consistent code style across a Python team or repository.
  • Running automatically as a pre-commit hook or in CI to check formatting.
  • Formatting Python code in Jupyter Notebooks alongside regular source files.

Quick start

  1. 1

    Install Black with pip

    pip install black
  2. 2

    Format a file or directory

    black {source_file_or_directory}

Things to know

  • Requires Python 3.10 or newer to run.

Topics

#python#code-formatter#linter#pep8#developer-tools#pre-commit#autopep8#code#codeformatter#formatter

FAQ

What is black?
Black is an opinionated, deterministic Python code formatter that rewrites files in place with minimal diffs. Black is an opinionated Python code formatter. It reformats entire files in place, with a deliberately small set of style options, so that code looks the same across projects and formatting debates are avoided. It is designed to produce the smallest possible diffs, which keeps code reviews focused on content.
Is black free to use? What license does it have?
black is open source under the MIT license. Check the license terms before using it in commercial products.
Is black still maintained?
Actively maintained. The last commit to black was on Oct 19, 2026.
What can I use black for?
Enforcing one consistent code style across a Python team or repository. Running automatically as a pre-commit hook or in CI to check formatting. Formatting Python code in Jupyter Notebooks alongside regular source files.
How do I install black?
Install Black with pip: pip install black Format a file or directory: black {source_file_or_directory}
Where can I get black?
The source code and installation instructions are on GitHub: https://github.com/psf/black

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects