VSCodeでPythonのLintを設定する方法について

VSCodeでPythonを開発する場合、Lintを設定しておくと、コードを書いている段階でミスや問題のある書き方を検出できます。

たとえば、未使用のimport、未定義の変数、コーディング規約違反などをエディター上で確認できるため、バグの防止やコード品質の向上につながります。

現在のVSCodeでは、以前使われていた python.linting.* 系の設定ではなく、RuffやPylint、Flake8など、それぞれ専用の拡張機能を利用する方法が基本です。

新しくPythonの開発環境を構築する場合は、Python拡張機能とPylanceに加えて、Ruffを導入する構成がシンプルで扱いやすいでしょう。

PythonのLintとは

Lintとは、ソースコードを実行せずに解析し、問題になりそうな箇所を検出する仕組みです。

Pythonでは、Linterを利用することで、単純な入力ミスだけでなく、未使用のimportや未定義の変数なども検出できます。

Lintで検出できる問題

たとえば、次のようなコードがあります。

import os

print(user_name)

このコードには、

• os をimportしているものの使用していない
• user_name が定義されていない

という問題があります。

RuffなどのLinterを設定しておけば、このような問題をVSCode上で警告として表示できます。

未使用変数も検出できる

関数内で定義した変数を使用していない場合も、Lintの対象になることがあります。

def greet():
    name = "Taro"
    print("Hello")

この例では、name を定義していますが、その後使用していません。

Ruffでは、設定しているルールによって、このような未使用ローカル変数を検出できます。

LintとFormatの違い

Python開発では、LintとFormatを混同しないことも重要です。

Lintはコードの問題を検出する機能で、Formatはコードの見た目を自動的に整える機能です。

Lintの役割

Lintでは、次のような問題を検出します。

print(undefined_name)

undefined_name が定義されていないため、Linterによって問題として検出できます。

Formatの役割

Formatは、次のようなコードを、

x=1

次のように整形します。

x = 1

Pythonでは、RuffやPylint、Flake8などがLintに利用されます。

一方、Ruff FormatterやBlackなどはコードのFormatに利用できます。

VSCodeで利用できるPythonのLintツール

VSCodeでは、複数のPython向けLintツールを利用できます。

代表的なのは、Ruff、Pylint、Flake8です。

Ruff

Ruffは、Astralが開発している高速なPython向けLinter・Formatterです。

Rustで実装されており、非常に高速にコードを解析できるのが特徴です。

Ruffでは、Lintだけでなく、コードの自動修正、import整理、コードフォーマットなども利用できます。

主な特徴は次のとおりです。

• 高速にLintを実行できる
• 多数のLintルールに対応している
• 自動修正機能を利用できる
• importを整理できる
• Formatterとしても利用できる
• pyproject.toml で設定を管理できる

特に新規プロジェクトでは、複数のツールを組み合わせる代わりにRuffへまとめる構成も採用しやすくなっています。

Pylint

Pylintは、Pythonで長く利用されているLintツールです。

単純なスタイルチェックだけではなく、コード品質について比較的細かく解析できる特徴があります。

Pylintでは、

• コード品質のチェック
• コーディング規約のチェック
• エラーの検出
• リファクタリング候補の検出

などが可能です。

既存プロジェクトですでにPylintを利用している場合は、そのままPylintをVSCodeへ導入する方法が適しています。

Flake8

Flake8も代表的なPython向けLinterです。

Pyflakesやpycodestyleなどの機能を組み合わせて、Pythonコードの問題やスタイル違反を検出します。

Flake8を採用している既存プロジェクトでは、VSCodeでもFlake8拡張機能を使用すると、既存の開発ルールを維持しやすくなります。

Ruff・Pylint・Flake8のどれを使えばよいか

どのLinterを利用するかは、プロジェクトの方針によって異なります。

新規プロジェクトならRuffが使いやすい

特に決まったルールがない新規プロジェクトでは、Ruffが扱いやすい選択肢です。

RuffはLint、Formatter、import整理などをまとめて扱えるため、導入するツールを減らしやすいメリットがあります。

詳細なコード品質チェックならPylint

細かなコード品質チェックを行いたい場合は、Pylintも選択肢になります。

Pylintには独自の豊富なルールがあり、コード品質を厳密に管理したいプロジェクトに向いています。

既存プロジェクトでは現在のルールに合わせる

すでにFlake8やPylintが導入されているプロジェクトの場合、無理にRuffへ変更する必要はありません。

チーム開発では、既存のCIや開発ルールと同じLinterをVSCodeでも使用する方が管理しやすくなります。

VSCodeでRuffを設定する方法

新しくPythonのLint環境を構築する場合は、まずPython拡張機能とRuff拡張機能をインストールします。

Python拡張機能をインストールする

VSCode左側の「Extensions」を開きます。

WindowsやLinuxでは、次のショートカットでも開けます。

Ctrl + Shift + X

macOSでは次のとおりです。

Command + Shift + X

検索ボックスへ、

Python

と入力し、Microsoftが提供しているPython拡張機能をインストールします。

Python拡張機能では、Python環境の選択、デバッグ、テストなど、VSCodeでPython開発を行うための基本機能を利用できます。

Ruff拡張機能をインストールする

続いて、Extensionsで、

Ruff

と検索します。

Astral Softwareが提供しているRuff拡張機能をインストールします。

拡張機能IDは、

charliermarsh.ruff

です。

Ruff拡張機能を導入すると、Pythonファイルに対してLintやフォーマットなどの機能を利用できるようになります。

Python Interpreterを選択する

PythonをVSCodeで使用するときは、プロジェクトで利用するPython環境も選択しておきます。

Python: Select Interpreterを実行する

コマンドパレットを開きます。

WindowsやLinuxでは、

Ctrl + Shift + P

macOSでは、

Command + Shift + P

です。

続いて、

Python: Select Interpreter

を選択します。

使用するPython環境を指定します。

たとえば、

.venv
venv
Conda
Python 3.x

などが候補として表示されます。

InterpreterとLinter本体は必ずしも同じではない

注意したいのは、VSCodeで選択したPython Interpreterと、Linterが実際に使用する実行ファイルが必ずしも同じとは限らないことです。

Ruff、Pylint、Flake8などの拡張機能には、拡張機能に同梱されているLinterを利用する仕組みがあります。

そのため、Python Interpreterを選択しただけで、必ずその仮想環境にインストールしたLinterが利用されるとは限りません。

チーム開発などでLinterのバージョンまで統一したい場合は、プロジェクト環境へLinterをインストールしたうえで、使用する実行環境を明示的に設定すると管理しやすくなります。

RuffをPython環境へインストールする方法

RuffのVSCode拡張機能にはRuffが含まれているため、VSCode上だけでLintを利用するのであれば、必ずしも pip install ruff を実行する必要はありません。

ただし、ターミナルやCIでもRuffを使用する場合は、プロジェクト環境へインストールしておくと便利です。

pipでRuffをインストールする

次のコマンドを実行します。

python -m pip install ruff

環境によっては、

pip install ruff

でもインストールできます。

インストール後は、

ruff --version

でバージョンを確認できます。

Ruffが動作しているか確認する

Ruffを設定したら、実際に問題を検出できるか確認します。

未使用importを作成する

たとえば、次のコードを作成します。

import os

print("Hello")

os を使用していないため、Ruffの設定によっては未使用importとして警告が表示されます。

Problemsパネルを確認する

VSCodeでは、Lintで検出した問題をProblemsパネルでも確認できます。

WindowsやLinuxでは、

Ctrl + Shift + M

でProblemsパネルを開けます。

エディター上の波線だけでなく、プロジェクト内の問題を一覧で確認したい場合に便利です。

VSCodeのsettings.jsonでRuffを設定する

Ruffは、VSCodeの settings.json を使って動作を調整できます。

settings.jsonを開く

コマンドパレットから、

Preferences: Open User Settings (JSON)

を実行すると、ユーザー全体の設定を開けます。

プロジェクト単位で設定したい場合は、

Preferences: Open Workspace Settings (JSON)

を利用します。

RuffをFormatterとして使用する

Ruffにはコードフォーマット機能もあります。

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

次のように設定します。

{
    "[python]": {
        "editor.defaultFormatter": "charliermarsh.ruff",
        "editor.formatOnSave": true
    }
}

この設定を行うと、Pythonファイルを保存したときにRuff Formatterによってコードが整形されます。

保存時にRuffで自動修正する

Ruffでは、一部のLint違反を自動修正できます。

RuffだけにFix Allを限定する

次のように設定できます。

{
    "[python]": {
        "editor.codeActionsOnSave": {
            "source.fixAll.ruff": "explicit"
        }
    }
}

source.fixAll.ruff とすることで、Ruffの自動修正だけを対象にできます。

単純に、

"source.fixAll": "explicit"

と設定することもできますが、ほかの拡張機能が提供するFix Allも対象になる可能性があります。

Ruff専用の設定として管理するのであれば、source.fixAll.ruff の方が分かりやすいでしょう。

保存時にimportを整理する

Ruffではimportの整理も可能です。

source.organizeImports.ruffを設定する

次のように設定します。

{
    "[python]": {
        "editor.codeActionsOnSave": {
            "source.organizeImports.ruff": "explicit"
        }
    }
}

これによって、保存時にRuffによるimport整理を実行できます。

Ruffのおすすめsettings.json

Lintの自動修正、import整理、フォーマットをまとめて設定する場合は、次のような構成にできます。

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

これによって、

• Ruff Formatterによるフォーマット
• 自動修正可能なLint違反の修正
• importの整理

を保存時に実行しやすくなります。

pyproject.tomlでRuffのルールを設定する

チーム開発では、VSCode固有の設定だけでなく、Lintルール自体を pyproject.toml に書く方法が便利です。

基本的な設定例

たとえば、次のように設定できます。

[tool.ruff]
line-length = 88

[tool.ruff.lint]
select = ["E", "F", "I"]

この設定では、主に、

E
F
I

のルールを有効にしています。

Eルール

E は、主にpycodestyle由来のエラー系ルールです。

コーディングスタイルに関する問題などを検出できます。

Fルール

F はPyflakes由来のルールです。

未使用importや未定義名など、コード上の問題を検出できます。

Iルール

I は、Ruffのisort互換ルールです。

importの並び順や整理に関するチェックを行います。

selectとextend-selectの違い

Ruffでは、ルールの指定方法として select と extend-select があります。

select

次の設定では、

[tool.ruff.lint]
select = ["E", "F", "I"]

指定したルール群を選択します。

プロジェクトで利用するルールを明示的に管理したい場合に使えます。

extend-select

既存の設定へルールを追加したい場合は、

[tool.ruff.lint]
extend-select = ["I"]

という書き方もできます。

たとえばRuffの既存ルール構成を維持しつつ、import整理の I だけを追加したい場合に便利です。

select = ["E", "F", "I"] はあくまで設定例であり、すべてのPythonプロジェクトで必須というわけではありません。

Ruffをコマンドラインから実行する

RuffはVSCodeだけでなく、ターミナルからも利用できます。

プロジェクト全体をLintする

次のコマンドを実行します。

ruff check .

現在のディレクトリ以下を対象にLintが実行されます。

特定のPythonファイルをLintする

ruff check main.py

のようにファイルを指定することもできます。

自動修正できる問題を修正する

次のコマンドを使用します。

ruff check . --fix

ただし、すべてのLint違反を自動修正できるわけではありません。

--fix では、自動修正可能と判断された問題だけが修正されます。

Ruffでコードをフォーマットする

フォーマットする場合は、

ruff format .

を実行します。

Lint修正とフォーマットを続けて行う場合は、

ruff check . --fix
ruff format .

という流れで実行できます。

VSCodeでPylintを設定する方法

RuffではなくPylintを利用したい場合は、Pylint専用拡張機能を導入します。

Pylint拡張機能をインストールする

Extensionsで、

Pylint

と検索します。

Microsoftが提供しているPylint拡張機能をインストールします。

拡張機能IDは、

ms-python.pylint

です。

Pylintをpipでインストールする

プロジェクト環境にPylintをインストールしたい場合は、

python -m pip install pylint

を実行します。

ただし、Pylint拡張機能にはPylintが同梱されているため、VSCodeで利用するためにpipでのインストールが必須というわけではありません。

CLIやCIでも同じPylintを使いたい場合や、特定のバージョンをプロジェクトで固定したい場合にインストールするとよいでしょう。

Pylintの設定を変更する

Pylint拡張機能では、settings.json からオプションを指定できます。

最大行長を設定する

たとえば、

{
    "pylint.args": [
        "--max-line-length=120"
    ]
}

と設定できます。

特定のルールを無効にする

{
    "pylint.args": [
        "--disable=C0114"
    ]
}

のように指定できます。

プロジェクト全体のルールは、Pylint用の設定ファイルへまとめる方法もあります。

Pylintを入力中にも実行する

Pylintでは、入力内容が変化したタイミングでLintを実行する設定もあります。

pylint.lintOnChangeを有効にする

{
    "pylint.lintOnChange": true
}

と設定します。

ただし、大きなプロジェクトでは頻繁に解析が実行されることで、エディターの負荷が増える可能性があります。

必要がなければ、保存時を中心にLintを実行する運用でも十分です。

VSCodeでFlake8を利用する方法

Flake8を使用する場合も、現在は専用のVSCode拡張機能を利用します。

Flake8拡張機能をインストールする

Extensionsから、

Flake8

を検索し、Microsoftが提供しているFlake8拡張機能をインストールします。

Pylintと同様に、Flake8拡張機能にもLinterが同梱されています。

そのため、VSCodeで利用するだけなら、必ずしもPython環境へFlake8をインストールする必要はありません。

プロジェクト環境へFlake8をインストールする

必要な場合は、

python -m pip install flake8

でインストールできます。

CIやコマンドラインでも同じFlake8を利用する場合は、プロジェクト環境へ導入すると管理しやすくなります。

PylanceとLinterの違い

VSCodeでPythonを使用すると、Pylanceという拡張機能もよく利用されます。

Pylanceは言語サーバー

Pylanceは、主に次のような機能を提供します。

• コード補完
• IntelliSense
• 型情報の表示
• 定義ジャンプ
• import解析
• 静的型チェック

RuffやPylintとは役割が異なります。

PylanceとRuffは併用できる

たとえば、

Pylance
→ コード補完・型解析

Ruff
→ Lint・Formatter・自動修正

という分担ができます。

そのため、

Python
+
Pylance
+
Ruff

という構成は、現在のVSCodeでPython開発を始める際の分かりやすい選択肢です。

mypyはLintより型チェックが中心

mypyもPythonの静的解析ツールとしてよく利用されます。

ただし、mypyはRuffやFlake8のような一般的なLinterというより、静的型チェックを主な目的とするツールです。

Linterと型チェッカーを分けて考える

大まかには、

Ruff・Pylint・Flake8
→ 主にLint

mypy・Pyright
→ 主に型チェック

と考えると分かりやすいでしょう。

プロジェクトによっては、Ruffとmypyのように、Lintと型チェックを組み合わせることもあります。

古いpython.linting設定には注意する

インターネット上には、古いVSCode向けの記事も多数残っています。

python.linting.enabledは旧方式

たとえば、次のような設定が紹介されていることがあります。

{
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": true
}

現在は、この方式ではなく、それぞれのLintツールに対応した専用拡張機能を利用するのが基本です。

つまり、

Ruff
→ Ruff拡張機能

Pylint
→ Pylint拡張機能

Flake8
→ Flake8拡張機能

という形で導入します。

古い記事を参考にするときは、python.linting.* が使われていないか確認するとよいでしょう。

Lintが動作しない場合の確認方法

Lintを設定しても警告が表示されない場合は、いくつか確認するポイントがあります。

Pythonファイルとして認識されているか確認する

VSCode右下の言語モードが、

Python

になっているか確認します。

別の言語として認識されている場合、Python用Linterが正常に動作しない可能性があります。

Linter拡張機能が有効か確認する

Extensionsを開いて、利用しているLinterが有効になっているか確認します。

たとえば、

Ruff
Pylint
Flake8

などです。

Python Interpreterを確認する

コマンドパレットから、

Python: Select Interpreter

を実行し、利用したいPython環境が選択されているか確認します。

特に仮想環境を利用している場合は、プロジェクトの .venv などが選択されているか確認するとよいでしょう。

Problemsパネルを確認する

次のショートカットでProblemsパネルを開けます。

Ctrl + Shift + M

Lintで検出された問題が一覧表示されていないか確認します。

Outputや拡張機能のログを確認する

それでも原因が分からない場合は、VSCodeのOutputや各拡張機能のログを確認します。

Ruff、Pylint、Flake8などの実行エラーや設定ファイルの読み込みエラーが表示されている場合があります。

プロジェクトごとにLint設定を管理する

チーム開発では、個人のVSCode設定だけにLintルールを書かず、プロジェクト側でも設定を管理すると便利です。

ディレクトリ構成の例

my-project/
├── .vscode/
│   └── settings.json
├── src/
│   └── main.py
├── tests/
│   └── test_main.py
└── pyproject.toml

.vscode/settings.json にはVSCode固有の設定を書きます。

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

一方、pyproject.toml にはRuffのLintルールを記述します。

[tool.ruff]
line-length = 88

[tool.ruff.lint]
select = ["E", "F", "I"]

このように分けることで、

.vscode/settings.json
→ VSCode上の動作

pyproject.toml
→ プロジェクト共通のLintルール

と役割を整理できます。

VSCodeでPythonのLintを設定するときのおすすめ構成

新しいPythonプロジェクトで、特に既存ルールがない場合は、

Python
+
Pylance
+
Ruff

という構成が比較的シンプルです。

Python拡張機能

Python環境の選択やデバッグなど、VSCode上でPython開発を行うための基本機能を担当します。

Pylance

コード補完や型情報、定義ジャンプなど、Pythonコードを効率よく編集するための機能を担当します。

Ruff

Lint、Formatter、自動修正、import整理などを担当します。

それぞれ役割が異なるため、併用できます。

VSCodeでPythonのLintを設定する際のポイント

VSCodeでPythonのLintを設定するときに特に重要なのは、現在のVSCodeではLinterごとの専用拡張機能を利用するという点です。

古い python.linting.* 設定をそのまま使用するのではなく、Ruff、Pylint、Flake8などの拡張機能を導入します。

新規プロジェクトであれば、Python、Pylance、Ruffを組み合わせると、Lint、コード補完、型解析、フォーマットなどを比較的シンプルに構成できます。

また、Lintルールを pyproject.toml に記述しておけば、VSCodeだけでなくコマンドラインやCIでも同じルールを利用できます。

VSCode側の動作は .vscode/settings.json、Pythonプロジェクト共通のLintルールは pyproject.toml というように役割を分けて管理すると、個人開発だけでなくチーム開発でも設定を統一しやすくなるでしょう。

以上、VSCodeでPythonのLintを設定する方法についてでした。

最後までお読みいただき、ありがとうございました。