What is Black?

Black is a highly opinionated code formatter for Python. It's designed to enforce a consistent coding style across your projects. Unlike linters, which identify errors or enforce specific rules, Black takes your code and reformats it to adhere to its style guide. Say goodbye to arguing over style nits in code reviews.

Black is specifically designed for Python and therefore primarily formats .py files. It can also format string literals in your Python code, including those containing code in other languages like SQL.

Installing Black

With Trunk Check, you can automatically install and configure Black along with any relevant linters in a few straightforward steps. Here's how:

First, if you haven't already installed Trunk CLI, you can do so with the command below:

1curl https://get.trunk.io -fsSL | bash

Next, you can initialize Trunk from the root of your git repository:

1trunk init

This command will scan your repository and create a .trunk/trunk.yaml file that enables all linters, formatters, and security analyzers, recommended by Trunk Check. This includes Black if applicable to your project.

To see all available linters Trunk Check installed, simply run:

1trunk check list

If you find Black is not automatically enabled, you can do so by running:

1trunk check enable black

Alternatively, to disable Black run the command below. To disable other tooling applied by Trunk Check, simply replace black with the respective tool you're looking to disable.

1trunk check disable black

For more details on Trunk Check setup, see here.

Configuring Black

Many linters and formatters provide some mechanism to tweak their configuration, e.g. .eslintrc or Cargo.toml. Trunk is aware of all the ways individual tools are configured and supports them. This means linters you've already configured will continue to work exactly the same, just now supercharged by Trunk Check.

Black is designed to be uncompromising and it works out of the box with Trunk so there's no need to set up a custom configuration. However, it does have some knobs for tuning. You can configure these in a pyproject.toml at the root of your repo.

Since Black is a Python formatter, it's relevant to call out that Trunk uses hermetic runtime versions which you can override if needed. If you're using a newer version of Python than our default (3.10.8 at the time of writing) you can override it in trunk.yaml via:

1runtimes:
2  enabled:
3    - python@3.10.8

As always, you can view the defaults and configuration of everything Trunk runs via trunk config print. Note that Python runtime versions are specifically allowlisted to a limited set.

If you're interested in other tools, check out our open-source repository to see how we define and support 90+ linters and formatters.

Running Black

To check your code with Black, simply run the command below. This command executes Black, along with any other formatters and linters Trunk Check enabled on files you've modified.

1trunk check

If you prefer to only run formatters, execute the command below:

1trunk fmt

If you prefer to format your changed files with only Black's standards, run the following command:

1trunk fmt --filter=black

Although we'd recommend against it depending on the size of your repository, you can format all files with Black by running the command below.

1trunk fmt --all --filter=black

In most scenarios, you'll want to execute against modified files. Since Trunk is git-aware, it knows what you've changed, and by adding batched execution and caching, you end up with a much faster and smoother way to run Black and other tools.

Updating Trunk Check & Black

To upgrade the Trunk CLI along with all plugins and linters in your trunk.yaml simply run:

1trunk upgrade

We highly recommend running on the latest validated versions of tools as updates will frequently include important security fixes and additional valuable checks. Trunk only auto-suggests linter upgrades to versions that we have tested and support, so you may see a slight lag time when a new linter version is released.

Upgrade will also recommend new tools that have become applicable since the last time your repository was scanned. This can be a result of using new technologies in your repository or Trunk itself adding support for more tools. If you don't like a particular recommendation you can always run trunk check disable <linter> to teach Trunk not to recommend it.

Recommended Linters to Pair with Black

Black pairs well with several linters to provide comprehensive code quality checks:

1. Ruff: A fast tool for catching errors and enforcing coding style.

2. isort: For sorting and organizing imports in a consistent manner.

3. mypy: For static type checking, ensuring type correctness in your Python code.