{"id":429,"library":"black","title":"Black: The Uncompromising Code Formatter","description":"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.","status":"active","version":"26.3.1","language":"python","source_language":"en","source_url":"https://github.com/psf/black","tags":["code formatter","Python","Black"],"install":[{"cmd":"pip install black","lang":"bash","label":"Install Black"}],"dependencies":[{"reason":"Required for parsing TOML configuration files","package":"tomli","optional":false}],"imports":[{"note":"No common mistakes identified","symbol":"black","correct":"import black"}],"quickstart":{"code":"import os\nimport black\n\n# Format a Python file\nfile_path = os.environ.get('FILE_PATH', 'example.py')\nwith open(file_path, 'r') as f:\n    source_code = f.read()\nformatted_code = black.format_file_contents(source_code, fast=False)\nwith open(file_path, 'w') as f:\n    f.write(formatted_code)\n\n# Format a Python string\ncode = 'def foo():\\n    return 42'\nformatted_code = black.format_str(code, mode=black.FileMode())\nprint(formatted_code)","lang":"python","description":"This script demonstrates how to use Black to format a Python file and a Python code string."},"warnings":[{"fix":"Upgrade to Python 3.10 or later.","message":"Black no longer supports running with Python 3.9 due to compatibility issues.","severity":"breaking","affected_versions":"25.12.0 and later"},{"fix":"Install 'tomli' using pip.","message":"Ensure that the 'tomli' package is installed, as it is required for parsing TOML configuration files.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure 'example.py' exists in the current working directory or provide the correct path to the file.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-05-12T13:44:47.742Z","next_check":"2026-06-26T00:00:00.000Z","problems":[{"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.","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.","error":"'black' is not recognized as an internal or external command"},{"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).","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.","error":"zsh: command not found: black"},{"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>`).","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.","error":"error: cannot format <file.py>: Cannot parse: <line>:<column>: <syntax>"},{"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.","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.","error":"ModuleNotFoundError: No module named 'black'"},{"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`).","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.","error":"Black formatter not working (e.g., in VSCode, no formatting on save)"}],"ecosystem":"pypi","meta_description":null,"install_score":100,"install_tag":"verified","quickstart_score":0,"quickstart_tag":"stale","pypi_latest":null,"install_checks":{"last_tested":"2026-05-12","tag":"verified","tag_description":"installs cleanly on critical runtimes, fast import, recently tested","results":[{"runtime":"python:3.10-alpine","python_version":"3.10","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.47,"mem_mb":12.4,"disk_size":"22.4M"},{"runtime":"python:3.10-slim","python_version":"3.10","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.26,"mem_mb":11.9,"disk_size":"28M"},{"runtime":"python:3.11-alpine","python_version":"3.11","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.7,"mem_mb":11.2,"disk_size":"24.5M"},{"runtime":"python:3.11-slim","python_version":"3.11","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.43,"mem_mb":10.6,"disk_size":"30M"},{"runtime":"python:3.12-alpine","python_version":"3.12","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.57,"mem_mb":11.1,"disk_size":"16.3M"},{"runtime":"python:3.12-slim","python_version":"3.12","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.41,"mem_mb":10.6,"disk_size":"22M"},{"runtime":"python:3.13-alpine","python_version":"3.13","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.49,"mem_mb":11.2,"disk_size":"15.9M"},{"runtime":"python:3.13-slim","python_version":"3.13","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.4,"mem_mb":10.7,"disk_size":"21M"},{"runtime":"python:3.9-alpine","python_version":"3.9","os_libc":"alpine (musl)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.46,"mem_mb":12.5,"disk_size":"21.8M"},{"runtime":"python:3.9-slim","python_version":"3.9","os_libc":"slim (glibc)","variant":"default","exit_code":0,"wheel_type":null,"failure_reason":null,"install_time_s":null,"import_time_s":0.33,"mem_mb":12,"disk_size":"27M"}]},"quickstart_checks":{"last_tested":"2026-04-23","tag":"stale","tag_description":"widespread failures or data too old to trust","results":[{"runtime":"python:3.10-alpine","exit_code":1},{"runtime":"python:3.10-slim","exit_code":1},{"runtime":"python:3.11-alpine","exit_code":1},{"runtime":"python:3.11-slim","exit_code":1},{"runtime":"python:3.12-alpine","exit_code":1},{"runtime":"python:3.12-slim","exit_code":1},{"runtime":"python:3.13-alpine","exit_code":1},{"runtime":"python:3.13-slim","exit_code":1},{"runtime":"python:3.9-alpine","exit_code":1},{"runtime":"python:3.9-slim","exit_code":1}]}}