You can use Black within a GitHub Actions workflow without setting your own Python environment. Great for enforcing that your code matches the Black code style.
This action is known to support all GitHub-hosted runner OSes. In addition, only published versions of Black are supported (i.e. whatever is available on PyPI).
Finally, this action installs Black with the colorama extra so the --color flag should work fine.
Create a file named .github/workflows/black.yml inside your repository with:
name: Lint on: [push, pull_request] jobs: lint: runs-on: ubuntu-latest steps: - uses: actions/checkout@v6 - uses: psf/black@stable
We recommend the use of the @stable tag, but per version tags also exist if you prefer that. Note that the action's version you select is independent of the version of Black the action will use.
The version of Black the action will use can be configured via version or read from the pyproject.toml file. The action defaults to the latest release available on PyPI.
version can be any valid version specifier or just the version number if you want an exact version.
If you want to match versions covered by Black's stability policy, you can use the compatible release operator (~=):
- uses: psf/black@stable with: options: "--check --verbose" src: "./src" version: "~= 26.0"
To read the version from the pyproject.toml file instead, set use_pyproject to true. This will first look into the tool.black.required-version field, then the dependency-groups table, then the project.dependencies array and finally the project.optional-dependencies table. Note that this requires Python >= 3.11, so using the setup-python action may be required, for example:
- uses: actions/setup-python@v6 with: python-version: "3.11" - uses: psf/black@stable with: options: "--check --verbose" src: "./src" use_pyproject: true
This action only reads version specifiers from standard `pyproject.toml` locations. Poetry-specific dependency tables such as `tool.poetry.dependencies` are not parsed. If you manage `black` with Poetry, set `tool.black.required-version` or use the `version` input.
Security note: use_pyproject only accepts standard version specifiers for black (for example ==, ~=, >= and ranges like >=25,<26). Only versions available from PyPI are supported, so no commit SHAs or branch names. Direct references such as black @ https://... are also not supported. If your workflow runs on untrusted pull requests (for example from forks), prefer setting with.version explicitly.
If you want to include Jupyter Notebooks, it can be enabled by setting jupyter to true (default is false):
- uses: psf/black@stable with: jupyter: true
See the Jupyter Notebooks guide for more details.
You can also configure the arguments passed to Black via options (defaults to '--check --diff') and src (default is '.'). Please note that the --check flag is required so that the workflow fails if Black finds files that need to be formatted.
Here's an example configuration:
- uses: psf/black@stable with: options: "--check --verbose" src: "./src" jupyter: true version: "21.5b1"
By default the action also adds Black‘s output to the workflow’s job summary. Set summary to false to turn that off.
If you want to keep the output around, for example to upload it as an artifact or use it in a later step, set output-file to a path. The output is then written to that file as well as printed in the log.
- uses: psf/black@stable with: summary: false output-file: "black-output.txt"
The action provides the following outputs:
is_formatted: Set to "true" if any files were reformatted (or in --check mode, would be reformatted); "false" otherwise. This can be used to run subsequent steps conditionally (for example, auto-committing formatted changes).change_count: Number of files that were reformatted (or would be reformatted in --check mode).same_count: Number of files that were left unchanged.failure_count: Number of files that failed to reformat.These outputs are only accessible if the action version as well as with.version are both 26.10.0+.