フォーマッター／リンターしたい（ruff）

$ ruff --version
ruff 0.16.3

$ ruff format
$ ruff check
$ ruff check --statistics

ruffはRustで書かれたPython用のリンター&フォーマッタです。 これまでblack、isort、flake8を組み合わせてできたことをすべてruffに集約できます。 pyproject.tomlに設定を記述できるため、既存のPythonプロジェクトにも導入しやすいです。

注釈

Pythonのリンター＆フォーマッタの変遷は闇が深そうです。 時代とともにベストプラクティスが移り変わっている感じで、 これを使っておけばOKみたいな標準的なモジュールが存在しませんでした。 ruffは、そのような悩みを解決してくれるツールです。

インストールしたい（ruff）

  • pipでインストール

$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install ruff

  • pipxでインストール

$ pipx install ruff

  • uv toolでインストール

$ uv tool install ruff

  • poetryでプロジェクトに追加

$ poetry add ruff --group=dev

  • uvでプロジェクトに追加

$ uv add ruff --group dev

ruffはCLIツールなので、pipxやuv toolでグローバルにインストールできます。 プロジェクトに追加する場合は --group dev オプションで追加するとよいです。

設定したい（[tool.ruff]）

 1# pyproject.toml
 2
 3[tool.ruff]
 4# 対象となるPythonのバージョン
 5target-version = "py311"
 6
 7# 1行あたりの最大文字数
 8# デフォルトは88。100くらいにしてもよい説がある
 9line-length = 88
10
11# 未使用importの自動削除
12# fix = true
13
14# ruff check の設定
15[tool.ruff.lint]
16# チェックするルールセット
17select = [
18    "E",    # pycodestyle (PEP8)
19    "F",    # pyflakes（未使用変数・未定義参照など）
20    "I",    # import order（importの順序）
21    "B",    # bugbear（潜在的なバグ）
22    "UP",   # pyupgrade（新しい構文へ自動更新）
23    "N",    # pep8-naming（命名規則）
24    "C4",   # flake8-comprehensions（内包表記の改善）
25    "SIM",  # flake8-simplify（冗長な構文の簡略化）
26    "RUF",  # Ruff独自の拡張
27]
28
29# チェックしないルールセット
30ignore = [
31    "E501",    # 行の長さ
32]
33
34# 自動修正するルールセット
35fixable = ["ALL"]
36unfixable = []
37
38
39# import orderの設定
40[tool.ruff.lint.isort]
41combine-as-imports = true
42known-first-party = ["自作したパッケージ名"]
43
44# ruff formatの設定
45[tool.ruff.format]
46quote-style = "double"    # ["double" | "single"]
47indent-style = "space"    # ["space" | "tab"]
48line-ending = "lf"        # ["lf", "crlf", "native"]
49skip-magic-trailing-comma = false  # 末尾のカンマを残す（false） | 残さない（true）
50docstring-code-format = true  # docstringも整形する（true） | 整形しない（false）

Ruffの設定はpyproject.tomlの[tool.ruff]セクションに記述できます。 また、ruff.toml、.ruff.tomlに個別設定として保存することもできます。

フォーマットしたい（ruff format）

$ ruff format
$ ruff format --check
$ ruff format --diff
$ ruff format ファイル名

formatコマンドでフォーマッターとして利用できます。 引数にファイル名を指定したり、確認したいディレクトリでruff format .を指定して実行します。

1[tool.ruff]
2line-length = 100
3
4[tool.ruff.format]
5quote-style = "double"

リンターしたい（ruff check）

$ ruff check .
$ ruff check ファイル名

ruff checkコマンドでリンターを実行します。 引数にファイル名やディレクトリを指定できます。 ruff check .でプロジェクト内のすべての該当するファイルを指定できます。

$ ruff check --show-fixes
$ ruff check --fix

--show-fixesで修正が必要な箇所を表示します。 --fixで軽微な修正を自動修正できます。 修正された箇所はターミナルに出力されます。

$ ruff check ファイル名 --select カテゴリ記号
$ ruff check . --select ALL
$ ruff check . --select E,F,W,I,D

--selectオプションを使って、チェックしたいカテゴリーやエラー番号などを指定できます。

$ ruff check --statistics
$ ruff check --statistics --select ALL

--statisticsオプションと--select ALLを使って、 どのルールを有効にすればよいか確認できます。

ルールを確認したい（ruff rule）

$ ruff rule ルールID

selectやignoreで設定できるカテゴリ記号は公式ドキュメントの「ルール」に書いてあります。 ruff linterコマンドでも、インストールされているバージョンのカテゴリ記号一覧を確認できます。 バージョンが上がるたびに追加・変更されるため（記号が短縮されたり、新しいカテゴリーが増えたりします）、 最新の一覧はコマンドか公式ドキュメントで確認するのが確実です。

$ ruff linter

よく使われる代表的なカテゴリーは次の通りです。

  • E, W: pycodestyle

  • F: Pyflakes

  • I: isort

  • N: pep8-naming

  • UP: pyupgrade

  • B: flake8-bugbear

  • C4: flake8-comprehensions

  • SIM: flake8-simplify

  • RUF: Ruff-specific rules

コミットフックしたい（ruff-pre-commit）

repos:
- repo: https://github.com/astral-sh/ruff-pre-commit
  rev: v0.15.12
  hooks:
  # ruff check
  - id: ruff-check
  # ruff format
  - id: ruff-format

ruff用のフックがあるので、pre-commitと連携させることができます。

id: ruff-checkを有効にすると ruff check .が実行されます。 ファイルは修正されません。

id: ruff-formatを有効にすると ruff format .が実行されます。 ファイルは修正されます。

注釈

以前はid: ruffという名前でしたが、現在はレガシーな別名として扱われています。 新しく設定する場合はruff-checkを使ってください。

リファレンス