Black: The Uncompromising Code Formatter

26.3.1 verified Tue May 12 auth: no python install: verified quickstart: stale

Black is an uncompromising Python code formatter that reformats code to improve readability. It is currently at version 26.3.1 and follows a regular release cadence, with new versions typically released every few months.

pip install black

Common errors

error 'black' is not recognized as an internal or external command ↓

cause The 'black' executable is not found in the system's PATH environment variable, or it is not installed in the currently active Python environment's scripts directory. This is common on Windows or when the virtual environment is not activated correctly.

fix

Ensure Black is installed in your active Python environment (pip install black). If it still doesn't work, try running it as a Python module (python -m black <filename>) or add the Python scripts directory (e.g., C:\PythonXX\Scripts or venv\Scripts) to your system's PATH.

error zsh: command not found: black ↓

cause The 'black' executable is not found in the shell's PATH. This typically happens in Unix-like environments (macOS, Linux) when the virtual environment where 'black' is installed is not activated, or the installation directory is not included in the shell's PATH.

fix

Activate your Python virtual environment where Black is installed. If not using a virtual environment, ensure Black is installed globally (pip install black) and your shell's PATH includes the directory where pip installs executables (often ~/.local/bin or a similar location).

error error: cannot format <file.py>: Cannot parse: <line>:<column>: <syntax> ↓

cause Black encountered a syntax error in the Python code or the code uses syntax from a Python version that is newer than what Black is currently configured or capable of parsing. Black does not format code that contains parsing errors.

fix

Correct any actual syntax errors in your Python file. If the syntax is valid for a newer Python version (e.g., Python 3.10's structural pattern matching), ensure you are running a recent version of Black that supports that Python version, and if necessary, use the --target-version flag (e.g., black --target-version py310 <file.py>).

error ModuleNotFoundError: No module named 'black' ↓

cause The 'black' package is not installed in the specific Python environment that is being used by the interpreter or application attempting to import or run Black. This is a common issue when working with virtual environments or when an IDE uses a different Python interpreter than expected.

fix

Install Black in the relevant Python environment using pip install black. If you are using an IDE like VSCode or PyCharm, ensure that the IDE is configured to use the Python interpreter where Black has been installed.

error Black formatter not working (e.g., in VSCode, no formatting on save) ↓

cause This usually indicates that the IDE is not correctly configured to use Black as the default Python formatter, or it is using a Python interpreter where Black is not installed or accessible.

fix

In VSCode, verify that "python.formatting.provider": "black" and "editor.formatOnSave": true are set in your settings.json. Most importantly, ensure the Python interpreter selected in your IDE (visible in the status bar in VSCode) corresponds to the environment where you have installed black (pip install black). Manually select the correct interpreter if needed (e.g., via VSCode's Command Palette: Ctrl+Shift+P -> Python: Select Interpreter).

Warnings

breaking Black no longer supports running with Python 3.9 due to compatibility issues. ↓

fix Upgrade to Python 3.10 or later.

gotcha Ensure that the 'tomli' package is installed, as it is required for parsing TOML configuration files. ↓

fix Install 'tomli' using pip.

gotcha The script failed because a required file 'example.py' was not found. This typically indicates that the file is missing from the working directory or the specified path is incorrect. ↓

fix Ensure 'example.py' exists in the current working directory or provide the correct path to the file.

breaking The script terminated due to a FileNotFoundError for 'example.py'. This indicates that a required file was not found at the specified path during execution. ↓

fix Ensure that 'example.py' is present in the expected location (e.g., the current working directory) or that the path to the file is correct within the execution environment.

Install compatibility verified last tested: 2026-05-12

python os / libc status wheel install import disk

3.10 alpine (musl) - - 0.47s 22.4M

3.10 slim (glibc) - - 0.26s 28M

3.11 alpine (musl) - - 0.70s 24.5M

3.11 slim (glibc) - - 0.43s 30M

3.12 alpine (musl) - - 0.57s 16.3M

3.12 slim (glibc) - - 0.41s 22M

3.13 alpine (musl) - - 0.49s 15.9M

3.13 slim (glibc) - - 0.40s 21M

3.9 alpine (musl) - - 0.46s 21.8M

3.9 slim (glibc) - - 0.33s 27M

Imports

black
```
import black
```
No common mistakes identified

Quickstart stale last tested: 2026-04-23

This script demonstrates how to use Black to format a Python file and a Python code string.

import os
import black

# Format a Python file
file_path = os.environ.get('FILE_PATH', 'example.py')
with open(file_path, 'r') as f:
    source_code = f.read()
formatted_code = black.format_file_contents(source_code, fast=False)
with open(file_path, 'w') as f:
    f.write(formatted_code)

# Format a Python string
code = 'def foo():\n    return 42'
formatted_code = black.format_str(code, mode=black.FileMode())
print(formatted_code)