Pythonコードを自動整形するblack×flake8×isortについて解説

2025年9月22日2025年12月24日

Python

Pythonでは、コードスタイルを自動で整えるツールが充実しています。

特にblack・flake8・isortの3つを組み合わせると、読みやすく保守しやすいコードベースを簡単に維持できるようになります。

本記事では、それぞれの役割から導入方法、設定例、チーム開発でのベストプラクティスまで、実務でそのまま使える形で詳しく解説します。

目次 [ close ]

black×flake8×isortとは何か

Pythonコード自動整形ツールの役割

Pythonのコード整形では「フォーマット」「静的解析」「インポート整理」の3つを分けて考えるとわかりやすいです。

black・flake8・isortは、それぞれ以下のような役割を持ちます。

Pythonのコード品質を高めるためには、単に見た目を整えるだけではなく、文法的なエラーを防ぎ、スタイルの一貫性を保つことが重要です。

そこで、blackがコードのフォーマット担当、flake8がコードスタイルとエラーチェック担当、isortがインポート整理担当という形で役割分担をしています。

いずれもコマンドラインから実行でき、VSCodeなどのエディタやgitのpre-commitフックとも連携しやすいため、日々の開発フローに自然に組み込むことができます。

blackの特徴

blackは「妥協なきコードフォーマッタ」と呼ばれる自動整形ツールです。

最大の特徴は設定項目がほとんどなく、決められたスタイルに強制的に揃える点です。

blackの主な特徴は次の通りです。

インデント・改行・空行・スペースなどを自動で統一
文字列のクオートを原則として'シングルクオート'から"ダブルクオート"に統一
行の長さをline-lengthで制御可能(デフォルトは88文字)
可能な限り同じ入力には同じ出力を保証する決定的なフォーマッタ

開発者がスタイルの細かい違いで議論する必要がなくなり、コードレビューではロジックに集中できるようになります。

flake8の特徴

flake8はコードスタイルと静的解析をまとめて行うチェックツールです。

PEP8に基づいたスタイルチェックに加えて、未使用変数や未使用インポートなど、潜在的なバグの予防にも役立ちます。

主な役割は次のように整理できます。

PEP8に準拠したスタイルチェック(E,W系のエラー)
文法的な問題の検出(F系のエラー)
未使用インポート・未使用変数の検出
外部プラグインによる拡張(mypy・docstringチェックなどと連携可能)

flake8は.flake8やpyproject.tomlに設定を書くことで、どのルールを無効にするか、どのディレクトリを除外するかなど、柔軟にカスタマイズできます。

isortの特徴

isortはimport文の並び順やグループ分けを自動で整える専用ツールです。

Pythonのインポートは、標準ライブラリ・サードパーティ・自作モジュールなどが混在しやすく、放っておくと非常に読みにくくなります。

isortは、以下のようなルールに基づいて自動整理します。

import文をアルファベット順に並び替え
標準ライブラリ・サードパーティ・ローカルモジュールなどでグルーピング
同じモジュールからの複数インポートを1行にまとめるなどの最適化

blackと組み合わせる際は、両者のルールがぶつからないように設定を揃えることが重要になります。

具体的な設定方法は後半のセクションで紹介します。

black×flake8×isortの導入方法

必要なパッケージのインストール

この3つのツールは、基本的にpipでインストールします。

プロジェクト単位で導入するのが一般的です。

仮想環境の準備とインストール例

まずは仮想環境を用意してから、ツールをインストールします。

Shell

# 仮想環境の作成(venvを利用する例)
python -m venv .venv

# 仮想環境の有効化(Windows)
.venv\Scripts\activate

# 仮想環境の有効化(macOS / Linux)
source .venv/bin/activate

# black, flake8, isort のインストール
pip install black flake8 isort

black・flake8・isortは開発時のみ使用するツールなので、後述するように本番用と開発用で依存関係を分けて管理すると運用しやすくなります。

pyproject.tomlによる設定管理

最近のPythonプロジェクトでは、設定をできるだけpyproject.tomlに集約するのが主流になりつつあります。

blackとisortはpyproject.tomlでの設定に正式対応しており、flake8も新しめのバージョンではpyproject.tomlに対応しています。

代表的なpyproject.toml設定例

ここでは、black・isort・flake8を一括で設定する例を示します。

TOML

[tool.black]
line-length = 88                # 1行の最大文字数
target-version = ["py311"]      # 対応するPythonバージョン
skip-string-normalization = false  # 文字列のクオート変換を有効にする
exclude = """
/(
    \.git
  | \.venv
  | build
  | dist
)/
"""

[tool.isort]
profile = "black"               # black と相性の良い設定プリセット
line_length = 88
multi_line_output = 3
include_trailing_comma = true
known_first_party = ["your_package_name"]  # 自作パッケージ名を指定
virtual_env = ".venv"

[tool.flake8]
max-line-length = 88
extend-ignore = [
  "E203",  # blackとの衝突を避けるため無視
  "W503",  # same as above
]
exclude = [
  ".git",
  "__pycache__",
  ".venv",
  "build",
  "dist",
]

この例では、3つのツールの行長(line length)を88で揃え、isortにはprofile = "black"を指定し、さらにflake8ではblackと衝突しがちなルールを無効化しています。

requirements(dev).txtへの追記

プロジェクトの依存関係をファイルで管理する場合、本番用のrequirements.txtと、開発用のrequirements-dev.txtを分ける構成がよく使われます。

例えば、次のようにrequirements-dev.txtを用意します。

# requirements-dev.txt

black==24.4.2
flake8==7.0.0
isort==5.13.2
pre-commit==4.0.1

インストール時は次のようにします。

Shell

pip install -r requirements-dev.txt

このように分けておくことで、本番環境には不要な開発ツールをインストールしないようにできます。

また、CI環境ではこの開発用依存関係だけを追加インストールして、コードチェックだけを行うといった運用も可能です。

black×flake8×isortの基本的な使い方

コマンドラインでの実行方法

それぞれのツールは、コマンドラインからシンプルなコマンドで実行できます。

ここでは、典型的な実行例を紹介します。

blackの基本コマンド

Shell

# カレントディレクトリ配下の .py ファイルを一括整形
black .

# 特定のファイルのみ整形
black app/main.py

# 整形内容を実際には書き込まず差分だけ確認
black --diff app/main.py

黒く塗る(black)という名前の通り、実行すると対象ファイルがその場で上書きされます。

差分だけ確認したい場合には--diffが便利です。

flake8の基本コマンド

Shell

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

# 特定ディレクトリを指定
flake8 app tests

# 一部のエラーコードを無視して実行
flake8 . --ignore=E203,W503

flake8はコードの書き換えは行わず、問題を検出して報告するだけです。

CIで失敗させるかどうかをエラーコードベースで制御することもできます。

isortの基本コマンド

Shell

# import文を自動整形(実際にファイルを上書き)
isort .

# 差分のみ表示
isort . --diff

# 特定ファイルのみ
isort app/main.py

isortもblackと同様に、基本的には対象ファイルをその場で上書きします。

初回は–diffでどの程度整形されるか確認してから適用すると安心です。

VSCodeなどエディタ連携の設定

毎回コマンドラインから実行するのは手間がかかるため、エディタ保存時に自動整形されるようにすると効率が上がります。

ここではVSCodeを例に設定を説明します。

VSCodeの設定例(settings.json)

VSCodeでは、.vscode/settings.jsonに設定を記述しておくと、プロジェクトごとにエディタの挙動を制御できます。

以下は代表的な設定例です。

JSON

{
  // Pythonインタプリタ(仮想環境)の指定
  "python.defaultInterpreterPath": ".venv/bin/python",

  // フォーマッタとして black を使用
  "python.formatting.provider": "black",
  "python.formatting.blackArgs": [
    "--line-length",
    "88"
  ],

  // ファイル保存時に自動でフォーマット実行
  "editor.formatOnSave": true,

  // isortをimport整理ツールとして設定
  "python.sortImports.args": [
    "--profile=black",
    "--line-length",
    "88"
  ],

  // Pythonファイル保存時にisortも実行
  "[python]": {
    "editor.codeActionsOnSave": {
      "source.organizeImports": "explicit"
    }
  },

  // flake8 をLintツールとして使用
  "python.linting.enabled": true,
  "python.linting.flake8Enabled": true,
  "python.linting.flake8Args": [
    "--max-line-length=88",
    "--extend-ignore=E203,W503"
  ]
}

このように設定しておくと、Pythonファイル保存時にblackによるフォーマット→isortによるインポート整形→flake8によるチェックという流れが自動で実行されるようになります。

pre-commitフックによる自動整形

さらに一歩進めて、gitのコミット前に必ずblackやisortを走らせる仕組みを導入すると、スタイルの乱れをリポジトリに持ち込まない運用が可能になります。

その定番がpre-commitフレームワークです。

pre-commitの設定例(.pre-commit-config.yaml)

まず、requirements-dev.txtなどでpre-commitをインストールしておいたうえで、プロジェクトルートに.pre-commit-config.yamlを作成します。

YAML

repos:
  - repo: https://github.com/psf/black
    rev: 24.4.2        # 使用したいblackのバージョン
    hooks:
      - id: black
        language_version: python3.11

  - repo: https://github.com/PyCQA/isort
    rev: 5.13.2
    hooks:
      - id: isort

  - repo: https://github.com/pycqa/flake8
    rev: 7.0.0
    hooks:
      - id: flake8
        additional_dependencies: []

設定ファイルを作成したら、以下のコマンドでフックをインストールします。

Shell

# pre-commitフックのインストール
pre-commit install

# 既存の全ファイルに対して一度だけすべてのフックを実行
pre-commit run --all-files

これで、以後git commitを実行すると自動的にblack・isort・flake8が走り、問題があればコミットが拒否されるようになります。

black×flake8×isortを併用するベストプラクティス

blackとflake8の設定調整

blackとflake8は、何も設定しないとルールが衝突する部分があります。

代表的なのがE203とW503に関するルールです。

この衝突を避けるために、flake8側で特定のルールを無効化するのが一般的です。

pyproject.tomlに設定する場合は、次のように指定します。

TOML

[tool.flake8]
max-line-length = 88
extend-ignore = [
  "E203",  # blackのスライス表現スタイルと衝突
  "W503",  # 演算子の前で改行するスタイルと衝突
]

また、max-line-lengthをblackと揃えておくことも重要です。

ここがバラバラだと、blackは通るがflake8では行長オーバーエラーになるといった事態が発生します。

isortとblackの競合を避ける設定

isortとblackは、ともにコードの見た目を変えるツールなので、設定が噛み合わないと整形のたびにお互いの変更を打ち消し合うことがあります。

その解決策として、isortにprofile = "black"を指定するのが定番です。

isort設定例(blackとの統合)

TOML

[tool.isort]
profile = "black"
line_length = 88
include_trailing_comma = true
multi_line_output = 3

profile = “black”とすることで、行末のカンマや改行位置など、blackと整合性の取れたスタイルに調整されます。

これにより、次のようなパターンを避けられます。

isortがimport文の改行位置を変更 → その後blackが再度改行位置を変更 → 差分が無限に出続ける
blackが整えたimport構文を、isortが別のスタイルに戻す

また、実行順序も重要です。

通常はisort → black → flake8の順番で処理するのが安定します。

pre-commitの設定でも、この順序になるようにhookを並べておくとよいでしょう。

チーム開発でのコードスタイル統一方法

ツールを導入しても、チーム全員が同じ設定を使っていなければコードスタイルは揃いません。

そこで、次のような運用を徹底することが大切です。

共有すべき設定ファイル

チーム開発では、次のファイルを必ずリポジトリにコミットし、開発メンバー全員が同じものを参照するようにします。

pyproject.toml … black/isort/flake8の共通設定
.pre-commit-config.yaml … コミット前フックの設定
requirements-dev.txt … ツールのバージョンを固定

これにより、誰が実行しても同じバージョンと設定でツールが動くようになります。

CIとの連携

さらに、GitHub ActionsやGitLab CIなどのCI環境でblack・flake8・isortを実行し、問題があればマージをブロックすると、ルールの徹底度が一段と高まります。

簡単なGitHub Actionsの例を示します。

YAML

name: Lint

on:
  pull_request:
    branches: [ main ]

jobs:
  lint:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install dependencies
        run: |
          python -m pip install --upgrade pip
          pip install -r requirements-dev.txt

      - name: Run black
        run: black --check .

      - name: Run isort
        run: isort --check-only .

      - name: Run flake8
        run: flake8 .

ここでは--checkや--check-onlyオプションを使い、コードを書き換えずにスタイル違反を検出しています。

PR時に自動チェックされることで、「blackをかけ忘れた」「flake8の警告を見落とした」といった人的ミスを防げます。

まとめ

black・flake8・isortを組み合わせることで、Pythonコードの整形・インポート整理・スタイルチェックを自動化し、品質の高いコードベースを少ない手間で維持できるようになります。

ポイントは、pyproject.tomlなどで設定を一元管理し、blackとflake8、isortのルールが競合しないよう調整することです。

さらに、VSCode連携やpre-commitフック、CIによる自動チェックを導入すれば、チーム全体で統一されたスタイルを強制でき、レビューではロジックに集中しやすくなります。

まずは小規模なプロジェクトで試し、快適さを実感してから既存プロジェクトへ段階的に導入していくことをおすすめします。