What is Ruff?

Ruff is a static code analysis tool designed specifically for Python. Unlike many traditional linters, Ruff is built for speed and efficiency, enabling developers to integrate it seamlessly into their development workflow. It checks your Python code for syntactical errors, coding standard violations, and other types of issues that could potentially lead to bugs. It's versatile in managing various Python file types and effectively lints:

• .py files: Standard Python source files.

• .pyi files: Stub files used in type hinting.

• Jupyter Notebooks: Ruff can lint code cells within .ipynb files.

Installing Ruff

With Trunk Check, you can automatically install and configure Ruff 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 Ruff if applicable to your project.

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

1trunk check list

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

1trunk check enable ruff

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

1trunk check disable ruff

For more details on Trunk Check setup, see here.

Configuring Ruff

Most linters 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.

Ruff works out of the box with Trunk so there's no need to set up a custom configuration. If you're interested in our default config, feel free to take a look at our ruff.toml file.

You can also check out our open-source linter repository to see the 90+ linters we support and how we define them.

Running Ruff

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

1trunk check

If you prefer to check files you've modified with only Ruff, run the following:

1trunk check --filter=ruff

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

1trunk check --all --filter=ruff

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 Ruff and other tools.

Updating Trunk Check & Ruff

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 Ruff

While Ruff is powerful on its own, pairing it with other linters can provide a more comprehensive code quality check. Here are some recommended linters to use alongside Ruff:

• Black: An opinionated code formatter. Black can automatically format your code in a way that adheres to many of Ruff’s checks.

• Mypy: For type checking. Mypy complements Ruff by providing static type analysis, which Ruff does not cover.

• Bandit: Focused on finding common security issues in Python code. Pairing Ruff with Bandit ensures both code quality and security.

Linters Ruff Replaces

Ruff is designed to supplant several older Python linters by offering more efficient and faster analysis without compromising on the depth of checks. Some of the notable linters that Ruff can replace include:

• Pylint: Known for its thorough checks but can be slow on larger codebases.

• PyFlakes: Focuses on logical errors in code; Ruff covers these and more.

• PEP8: Checks for style guide adherence, which is also a part of Ruff’s functionality.

• Flake8: Ruff offers an overlapping ruleset with Flake8.