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.
Install & Compatibility
Where this runs
tested against v26.5.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.925 runs
installs and imports cleanly · install 0.0s · import 0.540s · 22.7MB
glibcpy 3.10–3.925 runs
installs and imports cleanly · install 2.3s · import 0.363s · 28MB
23MB installed
● package 23MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
black
✓ import black
No common mistakes identified
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)
black --version
Debug
Known issues
breakingBlack no longer supports running with Python 3.9 due to compatibility issues.fixUpgrade to Python 3.10 or later.
affects: 25.12.0 and later
gotchaEnsure that the 'tomli' package is installed, as it is required for parsing TOML configuration files.fixInstall 'tomli' using pip.
affects: All versions
gotchaThe 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.fixEnsure 'example.py' exists in the current working directory or provide the correct path to the file.
affects: All versions
breakingThe script terminated due to a FileNotFoundError for 'example.py'. This indicates that a required file was not found at the specified path during execution.fixEnsure 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.
affects: All versions
Errors
Common errors & fixes
'black' is not recognized as an internal or external command
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.
fixEnsure 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.
zsh: command not found: black
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.
fixActivate 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: cannot format <file.py>: Cannot parse: <line>:<column>: <syntax>
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.
fixCorrect 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>`).
ModuleNotFoundError: No module named 'black'
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.
fixInstall 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.
Black formatter not working (e.g., in VSCode, no formatting on save)
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.
fixIn 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`).
Audit
Dependencies
tomlirequiredRequired for parsing TOML configuration files