Skip to content
Back to top
View this page

# GitHub Actions integration

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.

## Compatibility

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.

## Usage

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.

### Versions

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: "~= 22.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:

Security note: `use_pyproject` only accepts standard version specifiers for `black` (for example `==`, `~=`, `>=` and ranges like `>=25,<26`). Direct references such as `black @ https://...` are not supported. If your workflow runs on untrusted pull requests (for example from forks), prefer setting `with.version` explicitly.

    - uses: actions/setup-python@v6
      with:
        python-version: "3.13"
    - uses: psf/black@stable
      with:
        options: "--check --verbose"
        src: "./src"
        use_pyproject: true

Only versions available from PyPI are supported, so no commit SHAs or branch names.

### Jupyter Notebooks

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.

### CLI Options

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"