Pythonの自動整形と静的チェック(Black/flake8/isort)設定入門

2025年9月22日

Python

コードの見た目やインポート順序がまちまちなプロジェクトは、メンテナンス性が下がり、レビューも難しくなります。

そこで活躍するのが自動整形や静的チェックのツールです。

本記事ではBlack・flake8・isortの基本、導入手順、設定、そしてVS Code連携までを、Python初心者でも迷わないように丁寧に解説します。

Pythonの自動整形と静的チェックの基本

Pythonにはコード品質を高めるためのツールがいくつか存在します。

ここではBlack・flake8・isortの役割を明確にし、全体像を掴んでいただきます。

Blackとは

Blackは「妥協のない」自動フォーマッタです。

スタイルの選択肢を極力排し、常に同じルールでコードを整形します。

これによりレビューで見た目の議論が減り、ロジックに集中できます。

基本的な特徴は次の通りです。

Blackはpyproject.tomlの[tool.black]に設定を書きます。

主な効能はコードレイアウトの統一です。
デフォルトの行長は88で、line-lengthで変更可能です。
--checkや--diffで差分確認だけを行えます。

flake8とは

flake8は静的解析(コード規約や潜在的なバグの兆候の検出)を行うツールです。

PEP 8準拠のチェックに加え、様々なプラグインで機能拡張が可能です。

設定は.flake8、setup.cfg、tox.iniなどで行います。

余分なインポート、未使用変数、複雑度などを検出できます。
エラーコード(E、W、F、C など)で指摘内容が分類されます。
Blackと競合しやすいチェックはextend-ignoreで抑止します。

isortとは

isortはインポート文の並べ替えと分割を自動で行います。

標準ライブラリ、サードパーティ、ローカルモジュールなどのグループに分け、アルファベット順で整列します。

設定はpyproject.tomlの[tool.isort]などに書きます。

Blackと合わせる場合はprofile = "black"を設定して衝突を避けます。
isort --check-onlyで整形の必要性だけを確認できます。

3つを併用する理由

役割が明確に異なるからこそ、組み合わせることで強力になります。

Blackはフォーマット、isortはインポート、flake8は静的チェックを担当します。

見た目を自動化し、規約違反を早期に検出することで、レビューのノイズを減らし、品質を保ちながら開発速度を上げられます。

以下の表は役割の違いを簡潔にまとめたものです。

ツール	主な役割	自動修正	代表的な設定場所	例コマンド
Black	コード整形	あり	pyproject.toml([tool.black])	`black . / black --check .`
isort	インポート順整形	あり	pyproject.toml([tool.isort])	`isort . / isort --check-only .`
flake8	静的解析(規約・バグ兆候)	一部(基本は指摘のみ)	.flake8、setup.cfg、tox.ini	`flake8`

注意

flake8は原則自動修正しません。

指摘に沿って自分で直すか、Blackやisortで直せる部分はツールに任せます。

導入手順

前提

Python 3.8以上を推奨します。

Windows、macOS、Linuxいずれでも利用できます。

複数プロジェクトで異なるバージョンのツールを使い分けるため、各プロジェクトごとに仮想環境(venv)を作ることをおすすめします。

pipでBlack/flake8/isortをまとめてインストール

既存プロジェクトにまとめて導入する最小手順を示します。

まずはプロジェクトのルートに移動し、必要なら仮想環境を有効化してから以下を実行します。

Shell

# 例: すでに仮想環境が有効な状態でインストール
pip install --upgrade black flake8 isort

インストール後はblack・flake8・isortコマンドが使えるようになります。

仮想環境(venv)での導入のすすめ

プロジェクトごとの独立性を保つためにvenvを使います。

OSごとの基本コマンドは次の通りです。

Shell

# 1) 仮想環境の作成
python -m venv .venv

# 2) 仮想環境の有効化
# macOS/Linux:
source .venv/bin/activate
# Windows (PowerShell):
.venv\Scripts\Activate.ps1

# 3) ツールのインストール
pip install --upgrade black flake8 isort

仮想環境をプロジェクト直下(.venv)に置くと、エディタ設定やCIで参照しやすくなります。

設定ファイルの最小例

pyproject.tomlにBlackを設定

Blackはpyproject.tomlの[tool.black]セクションに設定を書きます。

最小構成の例です。

TOML

# pyproject.toml
[tool.black]
line-length = 100         # 行の最大文字数(デフォルト88)
target-version = ["py38"] # 目標とするPythonバージョン
skip-string-normalization = true  # 既存のクォートを尊重する

line-lengthはプロジェクトの規模や周辺ツールと合わせて決めるとよいでしょう。

pyproject.tomlにisortを設定

isortはBlackと組み合わせるためにprofile = "black"を指定するのが定石です。

TOML

# pyproject.toml
[tool.isort]
profile = "black"       # Blackと整合する設定をまとめて適用
line_length = 100       # Blackと同じ値に合わせる
multi_line_output = 3   # 長いインポートの折り返しスタイル
include_trailing_comma = true

これにより、Blackとisortの改行やカンマに関するルールが一致します。

.flake8で基本設定

flake8は.flake8に設定を書くのが分かりやすいです。

Blackと衝突しやすいルールを抑止し、行長はBlackに合わせます。

INI

# .flake8
[flake8]
max-line-length = 100
extend-ignore =
    E203,  # Blackと相性が悪い: スライス前の空白
    W503,  # Blackと相性が悪い: 演算子前の改行
exclude =
    .venv,
    build,
    dist,
per-file-ignores =
    tests/*: D  # 例: テストではdocstring関連の警告(D*)を緩めたい場合

プロジェクト方針に合わせて、未使用インポート(F401)などの扱いも調整します。

設定ファイルの置き場所と優先順

Blackはpyproject.tomlのみを読み、カレントディレクトリから親ディレクトリへ探索します。

コマンドライン引数が最優先です。

isortはpyproject.toml、.isort.cfg、setup.cfgなどを探し、現在のディレクトリに近い設定が優先されます。

こちらも--profileなどのCLI指定が最優先です。

flake8は.flake8、setup.cfg、tox.iniを探索します。

同名ファイルが複数ある場合は、より近いディレクトリの設定が優先され、最終的にはコマンドラインオプションが上書きします。

注意

設定の重複があると混乱の元です。

原則としてBlackとisortはpyproject.toml、flake8は.flake8にまとめるのがシンプルです。

使い方と運用

ここからは実際のコマンドや、既存プロジェクトを一括整形する流れ、VS Code連携を解説します。

Blackの基本コマンド例

Blackはプロジェクトルートで実行します。

Shell

# すべてのPythonファイルを整形
black .

# 整形が必要かどうかのチェックのみ(CIで便利)
black --check .

# 変更内容の差分だけ表示
black --diff .

実行結果

reformatted app/main.py
reformatted tests/test_app.py
All done! ✨ 🍰 ✨
2 files reformatted.

flake8の基本コマンド例

flake8は指摘を標準出力に表示します。

Shell

# プロジェクト全体をチェック
flake8

# ディレクトリやファイルを指定
flake8 app/ tests/

実行結果

app/main.py:10:1: F401 'json' imported but unused
app/utils.py:45:80: E501 line too long (120 > 100 characters)

isortの基本コマンド例

isortはインポートを整えます。

Blackと同様にチェックモードもあります。

Shell

# すべてのPythonファイルのインポート順を整形
isort .

# 整形が必要かチェックのみ
isort --check-only .

実行結果

Fixing app/main.py
Skipped 1 files

既存プロジェクトを一括整形する手順

まずisort→Black→flake8の順で進めると効率が良いです。

最初にisortでインポートを整えてから、Blackで全体レイアウトを統一します。

最後にflake8で残った警告を洗い出し、必要に応じて修正します。

大きめのプロジェクトなら、作業の途中で小さくコミットすると差分の追跡が容易になります。

例: isortとBlackを適用し、コミット。続けてflake8の指摘を修正し、再度コミットといった段階的な進め方が安全です。

サンプルコードでのデモ

以下は、isortやBlack適用前の少し乱れたコードです。

Python

# sample_before.py
# 少し乱れたスタイルのサンプルスクリプト
import os,sys
import json
from datetime import datetime,  date

def greet(name:str)->str:
    # インデントやスペースの使い方、クォートなどが不統一
    now=datetime.now()
    return f"Hello, {name}! Today is {date.today()} at {now.strftime('%H:%M:%S')}"

if __name__=='__main__':
    # 未使用のjsonがあるなど、flake8が指摘します
    print(greet("Tools"))

isortとBlackを適用した後のコードは次のようになります。

Shell

isort sample_before.py
black sample_before.py

Python

# sample_before.py (整形後)
# スタイルが統一され、インポートも整理されます
from datetime import date, datetime

import os
import sys

def greet(name: str) -> str:
    now = datetime.now()
    return f"Hello, {name}! Today is {date.today()} at {now.strftime('%H:%M:%S')}"

if __name__ == "__main__":
    print(greet("Tools"))

このスクリプトを実行すると、次のような出力になります。

Shell

python sample_before.py

実行結果

Hello, Tools! Today is 2025-09-21 at 12:34:56

注意

実行結果の日時部分は実行時刻に依存して変わります。

flake8を実行すると、未使用のインポート(osやsys)が指摘されることがあります。

不要であれば削除しましょう。

VS Codeで保存時にBlack/isortを有効化

VS Codeでは拡張機能を使うと、保存時に自動整形できます。

以下を推奨します。

拡張機能をインストール:
- Python(ms-python.python)
- Black Formatter(ms-python.black-formatter)
- isort(ms-python.isort)

ワークスペースの.vscode/settings.jsonに次の設定を追加します。

JSON

{
  // Blackを既定のフォーマッタにする
  "editor.defaultFormatter": "ms-python.black-formatter",

  // 保存時に自動フォーマット
  "editor.formatOnSave": true,

  // 保存時にisortでインポートを整理(明示的に許可)
  "editor.codeActionsOnSave": {
    "source.organizeImports": "explicit"
  },

  // 仮想環境を自動検出しやすくする(推奨)
  "python.defaultInterpreterPath": ".venv/bin/python"
}

Windowsの場合のpython.defaultInterpreterPathは.venv\Scripts\python.exeに読み替えてください。

これで保存時にisortがインポートを整理し、Blackがコードを整えます。

VS Codeでflake8を有効化

flake8は専用拡張機能の導入をおすすめします。

拡張機能: Flake8(ms-python.flake8)

基本的には拡張機能が有効化されれば動作しますが、必要に応じてワークスペース設定で引数やパスを指定できます。

JSON

{
  // 仮想環境内のflake8を使うためのパス指定(必要な場合)
  "flake8.path": [
    ".venv/bin/flake8"
  ],
  // flake8に追加で渡す引数(設定ファイルで十分なら不要)
  "flake8.args": [
    "--max-line-length=100"
  ]
}

ルールの詳細は基本的に.flake8に集約し、VS Code側では最小限の上書きに止めると一貫性が保てます。

以下は、より実務で役に立つ運用上のコツです。

CIではisort --check-only .、black --check .、flake8の順で検証すると、失敗理由が把握しやすいです。
チーム開発では全員が同じ設定ファイルを共有しましょう。エディタ依存の設定は.vscode/settings.jsonとしてリポジトリに含めると迷いが減ります。
初回整形は大きな差分が出るため、事前に専用コミット1回でまとめると、以降のレビューが楽になります。