Guide · Open source
How to use Black: install and format Python code
Updated · written with AI from the project's own documentation and checked against our catalogue data
Black is a command-line tool that rewrites Python code into one consistent layout, so you stop spending time on spacing, line breaks and quote style. This guide is for Python developers and teams who want formatting handled automatically. After reading it, you will be able to install Black, format a file or folder, and understand the few settings it offers.
Blackpsf/black · ★ 42.1k · MIT Install options & downloads Quick start
- 1Check your Python version. Black requires Python 3.10 or newer to run. Confirm your Python version before installing.
- 2Install Black. Run pip install black in your environment.
- 3Run Black on a file or folder. Run black followed by the path to your source file or directory. Files are reformatted in place.
- 4Add a pyproject.toml if needed. Store any custom include or exclude settings in pyproject.toml so every run uses them.
- 5Automate the check. Add Black to a pre-commit hook or CI pipeline so formatting is enforced for the whole team.
What Black does and who it is for
Black is an opinionated formatter. It reformats entire files in place and has deliberately few style options, so projects that use it tend to look alike. The README says that by using it you give up control over the minutiae of hand-formatting, in return for speed, determinism and freedom from pycodestyle nagging about formatting.
Black is a good fit when you want formatting decided for you, or when your team wants every project to look the same. It is less suited to anyone who wants fine-grained control over formatting choices.
- Python developers who want formatting handled automatically
- Teams that want all code to look the same
- Projects that already use pre-commit hooks or CI checks
- People who prefer not to debate style rules
Install Black with pip
Black is installed by running pip. It requires Python 3.10 or newer to run. If you want to format Jupyter Notebooks, install the extra instead.
If running Black as a script does not work, the README says you can run it as a package.
- Requirement: Python 3.10+
- Standalone executables built with PyInstaller are available from the latest GitHub release, if you want to run Black without installing Python
pip install black
pip install "black[jupyter]"
python -m black {source_file_or_directory}Format a file or folder
To get started right away with sensible defaults, run black followed by the path to a source file or directory. Black reformats the files in place, so you may want to commit or back up your work first.
The README notes Black also checks that the reformatted code still produces a valid AST that is effectively equivalent to the original. This safety check slows processing down; the README says that if you are confident, you can use --fast.
black {source_file_or_directory}Configure Black with pyproject.toml
Black can read project-specific default values for its command line options from a pyproject.toml file. This is especially useful for setting custom --include and --exclude, --force-exclude or --extend-exclude patterns for your project.
The README's advice is that most projects need no configuration at all. Black is designed around sensible defaults, and applying them keeps your code in line with many other Black-formatted projects.
- Put options in pyproject.toml to avoid repeating them on the command line
- Use exclude patterns to skip files or folders you do not want formatted
Add Black to your workflow
The README lists Black as a tool many projects use to enforce a consistent code style. A common approach is to run it in a pre-commit hook or a CI check so every change is formatted the same way before review.
Black also aims to make code review faster by producing the smallest diffs possible, so reviewers can focus on logic rather than formatting.
- Run Black locally before committing
- Run Black as a check in your continuous integration pipeline
Know the style rules before you file an issue
Black follows PEP 8 and its style is documented in The Black Code Style, which covers the current style and planned future changes. The README says that now that Black is stable, large formatting changes are not expected; style changes mostly respond to bug reports and support for new Python syntax.
Because Black makes some deliberate exceptions, the README asks you to read the Pragmatism section before reporting something as a bug, since it may be intended behaviour.
- Read the current style documentation
- Check the Pragmatism section before reporting a bug
What people use it for
- Formatting a single Python script before sharing it
- Keeping all files in a team repository in the same style
- Reducing formatting noise in code review diffs
- Enforcing a consistent style through pre-commit hooks or CI checks
Frequently asked questions
How do I install Black?
Run pip install black. The README says Black requires Python 3.10 or newer to run. If you want to format Jupyter Notebooks, install pip install "black[jupyter]" instead.
Is Black free to use?
Black is released under the MIT licence, as stated in the project's README and licence file. The source says nothing about pricing beyond that.
Does Black need any configuration?
No. The README says Black is built around sensible defaults. You can add a pyproject.toml file for include and exclude patterns, but most projects do not need to change anything.
What Python versions does Black support?
The README says Black requires Python 3.10 or newer to run. Projects that must run on older Python versions should choose a different tool.
What are the alternatives to Black?
The comparable projects listed for this item are autopep8 and yapf. Black differs in that it has few settings by design, while those tools may offer more control over formatting.
Why did Black change my code in a way I did not expect?
Black is opinionated and reformats entire files. Before reporting a bug, the README asks you to check The Black Code Style and the Pragmatism section, because the behaviour may be intended.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Black suits Python developers and teams who want formatting decided automatically and a shared look across projects, especially if they already use pre-commit hooks or CI. Pick something else if you need detailed control over formatting choices or must support Python versions older than 3.10.
Install options & downloads