多くのPython開発者が、コード品質で以下のような悩みを抱えています。

まずは基本から。「フォーマッター」「リンター」「pre-commit」の3つの用語を理解しましょう。

フォーマッターを使うと、読みづらいコードが一瞬で整います。

def calculate(x,y,z):
result=x+y+z
return result

def process_data(data,options = {'key'  :'value'}):
if data>0:
return  data*2
return None

def calculate(x, y, z):
result = x + y + z
return result


def process_data(data, options={"key": "value"}):
if data > 0:
return data * 2
return None

リンターは、潜在的なバグやコーディング規約違反を自動検出します。

# リンターが検出する問題例
import os
import sys
import django  # ❌ E402: import順序が間違ってる（標準→サードパーティ）

def process_data(data):
result = data * 2
temp = 100  # ❌ F841: 未使用変数
return result

def calculate(x):
if x=10:  # ❌ E999: 構文エラー（== が正しい）
return x * 2

従来は、フォーマット・リント・import整理を別々のツールで実行していました。これが面倒で、多くの問題を引き起こしていました。

# 1. 複数ツールのインストール
pip install black flake8 isort

# 2. 設定ファイルが分散
# .flake8, pyproject.toml, setup.cfg...どこに何を書く？

# 3. 実行も別々
black .
isort .
flake8 .
# → 3コマンド打つのめんどくさい

# 4. 設定が競合
# Blackとflake8の行長設定が違ってエラー...

ruffは、Black、flake8、isort、pydocstyle等を1つに統合したオールインワンツールです。Rustで実装されており、従来ツールの10-100倍高速です。

ruffの導入は非常に簡単です。以下の4ステップで完了します。

• 01

  インストール（1分）

  Bash

  # uvを使う場合（推奨）
  uv pip install ruff
  
  # pipを使う場合
  pip install ruff
  
  # 確認
  ruff --version

  uvについては、uv記事を参照してください。

• 02

  初回実行（1分）

  Bash

  # フォーマット実行
  ruff format .
  
  # リント実行
  ruff check .
  
  # リント＋自動修正
  ruff check --fix .

  まずは設定なしで実行してみましょう。デフォルト設定でも十分使えます。

• 03

  設定ファイル作成（3分）

  設定のポイント

  プロジェクトルートに pyproject.toml を作成します。最初は緩めの設定で始めて、慣れたら厳しくするのがおすすめです。

  • line-length: 行の長さ（100文字推奨）
  • select: 有効にするルール
  • ignore: 無視するルール（E501は無視が現実的）

  ポイント: E501（行長すぎ）は無視するのが現実的。

  TOML: pyproject.toml

  [tool.ruff]
  # 行の長さ（デフォルト88、Blackと同じ）
  line-length = 100
  
  # Python バージョン
  target-version = "py311"
  
  [tool.ruff.lint]
  # 有効にするルール
  select = [
  "E",   # pycodestyle errors
  "W",   # pycodestyle warnings
  "F",   # pyflakes
  "I",   # isort（import整理）
  "N",   # pep8-naming
  ]
  
  # 無視するルール（現実的な設定）
  ignore = [
  "E501",  # line too long（100文字までOKにしてるので）
  ]
  
  [tool.ruff.lint.isort]
  # Django用のimport順序
  known-first-party = ["myproject"]

• 04

  VSCode設定（3分）

  自動フォーマットの設定

  .vscode/settings.json を作成して、保存時に自動フォーマットを有効化します。

  • defaultFormatter: ruffを設定
  • formatOnSave: 保存時に自動実行
  • codeActionsOnSave: リント＆import整理も自動化

  保存時に自動フォーマット！

  JSON: .vscode/settings.json

  {
  "[python]": {
  "editor.defaultFormatter": "charliermarsh.ruff",
  "editor.formatOnSave": true,
  "editor.codeActionsOnSave": {
  "source.fixAll": true,
  "source.organizeImports": true
  }
  }
  }

pre-commit導入後の開発フローを図解します。

サンプルリポジトリ（article-sample-src）での実例を紹介します。そのままコピーして使えます。

article-sample-src/
├── backend/
│   ├── pyproject.toml          # ruff設定
│   ├── .pre-commit-config.yaml # pre-commit設定
│   └── myproject/
└── .vscode/
└── settings.json           # VSCode設定

[tool.ruff]
line-length = 100
target-version = "py311"

# 除外ディレクトリ
exclude = [
"migrations/",
"*.pyi",
"__pycache__",
]

[tool.ruff.lint]
select = [
"E",   # pycodestyle errors
"W",   # pycodestyle warnings
"F",   # pyflakes
"I",   # isort
"N",   # pep8-naming
]

ignore = [
"E501",  # line too long
]

[tool.ruff.lint.isort]
known-first-party = ["myproject"]

repos:
- repo: local
hooks:
- id: ruff-check
name: ruff check
entry: ruff check --fix
language: system
types: [python]
pass_filenames: false

- id: ruff-format
name: ruff format
entry: ruff format
language: system
types: [python]
pass_filenames: false

ruffは、従来ツール（Black、flake8等）と比較して圧倒的に高速です。以下は、10万行のDjangoプロジェクトでの実測データです。

既存プロジェクトでBlackやflake8を使っている場合の移行手順です。

# 1. ruffインストール
uv pip install ruff

# 2. Blackアンインストール
pip uninstall black

# 3. ruff実行
ruff format .

# 1. ruffインストール
uv pip install ruff

# 2. 既存設定を移行
# .flake8の設定をpyproject.tomlに移す

# 3. 動作確認
ruff check .
ruff format .

# 4. 問題なければアンインストール
pip uninstall black flake8 isort

GitHub Actionsでruffを実行する例です。pre-commitだけでなく、CI/CDでもチェックすると安心です。

name: CI
on: [push, pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install uv
run: curl -LsSf https://astral.sh/uv/install.sh | sh
- name: Setup Python
run: |
    uv venv
    source .venv/bin/activate
    uv pip install ruff
- name: Run ruff
run: |
    ruff check .
    ruff format --check .

参考: GitHub Actions公式ドキュメント

• Ruff公式ドキュメント - 公式マニュアル、ルール一覧
• Ruff GitHub - ソースコード、Issues、ベンチマーク
• pre-commit公式サイト - pre-commitの使い方、設定例
• Black公式ドキュメント - Blackの思想、設定
• PEP 8 -- Style Guide for Python Code - Pythonコーディング規約
• Astral（開発元） - ruff、uvを開発するAstral社の公式サイト
• article-sample-src - この記事で紹介した設定の実例