VSCodeでPythonを開発する場合、Ruffを導入するとLint、コードフォーマット、import整理などをまとめて行えるようになります。
RuffはRustで実装された高速なPython向けツールで、Flake8、isort、pyupgradeなど複数のツールが担っていた機能を1つにまとめやすいのが特徴です。
VSCodeでは公式のRuff拡張機能を利用することで、コードを書きながらリアルタイムに問題を確認したり、保存時に自動修正やフォーマットを実行したりできます。
ここでは、VSCodeでRuffを設定する方法を詳しく解説します。
Ruffとは
Python向けのLinter・Formatter
Ruffは、PythonコードをチェックするLinterと、コードの書式を整えるFormatterの両方の機能を備えたツールです。
代表的には、次のような処理を行えます。
- 文法やコーディング規約のチェック
- 未使用importの検出
- import文の並び替え
- 古いPython構文の改善
- 修正可能な問題の自動修正
- コードフォーマット
これまでFlake8、isort、pyupgrade、Blackなどを組み合わせていた環境でも、用途によってはRuffへまとめることができます。
ただし、RuffとBlackを必ず一本化しなければならないわけではありません。
RuffをLint専用として使用し、FormatterにはBlackを使う構成も可能です。
VSCodeにRuff拡張機能をインストールする
Extensions画面を開く
まず、VSCodeで拡張機能画面を開きます。
WindowsやLinuxでは次のショートカットを使用できます。
Ctrl + Shift + X
macOSでは次のショートカットです。
Command + Shift + X
検索欄に次のように入力します。
Ruff
表示されたRuff拡張機能を選択してインストールします。
RuffのVSCode拡張機能はAstral Softwareによって提供されています。
Ruff本体は別途インストールする必要があるのか
VSCodeだけで使うなら必須ではない
VSCodeのRuff拡張機能にはRuff実行ファイルが同梱されています。
そのため、VSCode上だけでRuffを使うのであれば、必ずしも次のようなコマンドでRuffをインストールする必要はありません。
pip install ruff
Ruff拡張機能は利用可能なPython環境などからRuffを探し、必要に応じてPATH上や拡張機能に同梱されたRuffを利用できます。
CLIやCI/CDでも使うならインストールすると便利
一方で、ターミナルからRuffを実行したり、GitHub Actionsやpre-commitで使ったりする場合は、プロジェクト環境にRuffをインストールしておくと管理しやすくなります。
例えば、次のようにインストールできます。
pip install ruff
インストール後は次のコマンドで確認できます。
ruff --version
仮想環境にRuffをインストールする
Windowsの場合
プロジェクトごとにRuffを管理する場合は、仮想環境へインストールする方法が一般的です。
まず仮想環境を作成します。
python -m venv .venv
次に有効化します。
.venv\Scripts\activate
そのうえでRuffをインストールします。
pip install ruff
macOS・Linuxの場合
macOSやLinuxでは、例えば次のように設定できます。
python3 -m venv .venv
source .venv/bin/activate
pip install ruff
VSCodeでプロジェクトの仮想環境を使用する場合は、コマンドパレットから次を実行します。
Python: Select Interpreter
目的の.venvなどを選択しておくと、プロジェクト単位でPython環境を管理しやすくなります。
Ruffの設定ファイルを作成する
pyproject.tomlを利用する
Ruffの設定は、主に次のファイルに記述できます。
pyproject.toml
ruff.toml
.ruff.toml
Pythonプロジェクトでは、他のPython関連ツールの設定もまとめられるpyproject.tomlを使う方法が便利です。
例えば、次のような構成にできます。
project/
├─ .vscode/
│ └─ settings.json
├─ src/
│ └─ main.py
└─ pyproject.toml
VSCode固有の動作は.vscode/settings.jsonに記述し、Ruff自体のルールはpyproject.tomlにまとめると管理しやすくなります。
参考サイト
Pythonの Linter Formatter は、もうRuff一択。最短5分でプロジェクトに導入
pyproject.tomlの基本設定
基本的な設定例
Ruffの設定は、例えば次のように記述できます。
[project]
requires-python = ">=3.11"[tool.ruff]
line-length = 88
[tool.ruff.lint]
select = [“E”, “F”, “I”, “UP”]
[tool.ruff.format]
quote-style = “double” indent-style = “space”
Pythonの対象バージョンを設定する
requires-pythonを使う
pyproject.tomlを使っている場合は、プロジェクト全体のPythonバージョンとして次のように指定できます。
[project]
requires-python = ">=3.11"
Ruffはこの設定から対象Pythonバージョンを推測できます。
Ruffだけでなく、Pythonパッケージング全体で共有できる設定なのがメリットです。
target-versionを明示する
Ruff側で明示したい場合は、次のように設定できます。
[tool.ruff]
target-version = "py311"
Python 3.12なら次のようにします。
[tool.ruff]
target-version = "py312"
requires-pythonとtarget-versionの両方を設定した場合は、Ruff側のtarget-versionが優先されます。
line-lengthを設定する
1行の長さの目安を設定する
次の設定では、Ruff Formatterが1行の長さを判断する際の基準を88文字にします。
[tool.ruff]
line-length = 88
88文字はBlackでもよく使われる値です。
プロジェクトによっては次のように変更しても構いません。
line-length = 100
または、
line-length = 120
ただし、line-length = 88を設定したからといって、すべての行が必ず88文字以内になるわけではありません。
Ruff Formatterが改行を判断するための目安として使われます。
RuffのLintルールを設定する
selectで有効なルールを指定する
例えば次のように設定できます。
[tool.ruff.lint]
select = ["E", "F", "I", "UP"]
それぞれのおおまかな意味は次のとおりです。
E pycodestyle系のエラー
F Pyflakes
I isort系のimportチェック
UP pyupgrade
例えばFを有効にしている場合、未使用importなどを検出できます。
extend-selectを使うこともできる
Ruffのデフォルトルールへ追加する形でルールを増やしたい場合は、extend-selectも利用できます。
例えば次のように設定します。
[tool.ruff.lint]
extend-select = ["I", "UP"]
selectは有効にするルールセットを指定する設定です。
既存の設定に追加したい場合はextend-selectを使い分けるとよいでしょう。
RuffをVSCodeのFormatterに設定する
settings.jsonを開く
VSCodeのコマンドパレットを開きます。
WindowsやLinuxでは次のショートカットです。
Ctrl + Shift + P
macOSでは次のようになります。
Command + Shift + P
その後、次のいずれかを実行します。
Preferences: Open User Settings (JSON)
または、プロジェクト単位で設定したい場合はワークスペース設定を開きます。
保存時にRuff Formatterを実行する
formatOnSaveを有効にする
Pythonファイルの保存時にRuffでフォーマットする場合は、次のように設定できます。
{
"[python]": {
"editor.defaultFormatter": "charliermarsh.ruff",
"editor.formatOnSave": true
}
}
これにより、Pythonファイルを保存するとRuff Formatterが実行されます。
保存時にLintエラーを自動修正する
source.fixAll.ruffを設定する
FormatterとLintの自動修正は別の機能です。
そのため、editor.formatOnSaveだけではLintエラーがすべて自動修正されるわけではありません。
保存時にRuffによる修正も実行したい場合は、次のように設定します。
{
"[python]": {
"editor.defaultFormatter": "charliermarsh.ruff",
"editor.formatOnSave": true
},
"editor.codeActionsOnSave": {
"source.fixAll.ruff": "explicit"
}
}
Ruffが安全に自動修正できる問題について、保存時に修正できます。
保存時にimportを整理する
source.organizeImports.ruffを設定する
import文もRuffに整理させたい場合は、次の設定を追加します。
{
"[python]": {
"editor.defaultFormatter": "charliermarsh.ruff",
"editor.formatOnSave": true
},
"editor.codeActionsOnSave": {
"source.fixAll.ruff": "explicit",
"source.organizeImports.ruff": "explicit"
}
}
これにより、保存時にRuffによる自動修正、import整理、フォーマットを利用できます。
ただし、それぞれの処理が必ず特定の順番で実行されると考えない方が安全です。
おすすめのsettings.json
Python向けにRuffをまとめて設定する
実務では、次のような設定が扱いやすいです。
{
"[python]": {
"editor.defaultFormatter": "charliermarsh.ruff",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.ruff": "explicit",
"source.organizeImports.ruff": "explicit"
}
}
}
この設定では、Pythonファイルに対してのみRuffを使えます。
他のプログラミング言語のFormatterやCode Actionへ影響しにくい点もメリットです。
Ruffをコマンドラインから実行する
コードをチェックする
プロジェクト全体をLintする場合は、次のコマンドを実行します。
ruff check .
指定したファイルだけ確認する場合は次のようにします。
ruff check main.py
自動修正する
Ruffが修正できる問題を自動修正する場合は次のコマンドです。
ruff check --fix .
特定のファイルだけ修正する場合は次のようにします。
ruff check --fix main.py
フォーマットする
Ruff Formatterでコードを整形する場合は次のコマンドを使用します。
ruff format .
特定のファイルだけの場合は次のようになります。
ruff format main.py
つまり、基本的には次のように覚えると分かりやすいです。
ruff check .
→ Lint
ruff check --fix .
→ Lint＋自動修正
ruff format .
→ コードフォーマット
VSCode上でRuffのエラーを確認する
Pythonコードに問題があると警告が表示される
Ruff拡張機能が動作している場合、Pythonコードに問題があるとVSCode上に波線や警告が表示されます。
例えば次のコードでは、設定によってはosが未使用importとして検出されます。
import os
print("Hello")
Quick Fixを利用する場合は、問題がある場所で次のショートカットを使用できます。
WindowsやLinuxでは、
Ctrl + .
macOSでは、
Command + .
です。
Ruffが修正できる問題であれば、ここから修正できます。
RuffとPylanceは併用できる
役割が異なるため併用しやすい
Ruffを導入しても、Pylanceを削除する必要はありません。
RuffとPylanceでは担当する役割が異なります。
例えば、次のように分けられます。
Ruff
├─ Lint
├─ コードフォーマット
├─ import整理
└─ コード自動修正
Pylance
├─ 型解析
├─ コード補完
├─ 定義ジャンプ
└─ Hover情報
そのため、VSCodeのPython開発環境では、
Python
Pylance
Ruff
という構成にしても問題ありません。
Ruff FormatterとBlackはどちらを使うべきか
Ruff Formatterへ統一することもできる
すでにBlackを使用している場合でも、Ruff Formatterへ移行できます。
その場合は、Python用のデフォルトFormatterをRuffに設定します。
{
"[python]": {
"editor.defaultFormatter": "charliermarsh.ruff"
}
}
RuffとBlackの両方を同時に保存時Formatterとして動かす必要は通常ありません。
RuffはLintだけにする方法もある
一方で、次のような役割分担も可能です。
Ruff
→ Lint・自動修正
Black
→ Formatter
既存プロジェクトでBlackを利用している場合は、無理にRuff Formatterへ移行する必要はありません。
新規プロジェクトでツール数を減らしたい場合は、Ruffへまとめると構成をシンプルにできます。
Ruffとisortの関係
Ruffでimport整理を行える
RuffではIルールを利用することで、isort系のimportチェックや整理を行えます。
例えば次のように設定します。
[tool.ruff.lint]
select = ["E", "F", "I", "UP"]
さらにVSCode側で、
"source.organizeImports.ruff": "explicit"
を設定すれば、保存時にimport整理も利用できます。
そのため、新規プロジェクトではisortを別途導入せず、Ruffへまとめる構成も可能です。
ruff-lspは現在どうなっているのか
現在はruff serverが標準
以前のRuffでは、Pythonで実装されたruff-lspがLanguage Serverとして利用されていました。
現在のruff-lspは非推奨です。
Ruff本体にはRust製のLanguage Serverが含まれており、次のコマンドで起動できます。
ruff server
現在のRuff VSCode拡張機能では、条件を満たしていればこのネイティブなLanguage Serverが自動的に使用されます。
そのため、新しくRuffを設定する場合はruff-lspを前提に考える必要はありません。
unsafe fixには注意する
デフォルトでは安全な修正が中心
Ruffでは、自動修正を大きく安全な修正とunsafeな修正に分けています。
通常のFix Allでは、安全と判断された修正が中心に適用されます。
unsafe fixも許可する場合は、例えば次のような設定が可能です。
[tool.ruff.lint]
unsafe-fixes = true
ただし、コードの意味が変わる可能性がある修正も含まれるため、通常はデフォルト設定のまま使う方が安全です。
settings.jsonとpyproject.tomlは使い分ける
VSCode固有の設定はsettings.jsonへ書く
VSCode上での保存時処理などは.vscode/settings.jsonに記述すると分かりやすくなります。
例えば、
{
"[python]": {
"editor.defaultFormatter": "charliermarsh.ruff",
"editor.formatOnSave": true,
"editor.codeActionsOnSave": {
"source.fixAll.ruff": "explicit",
"source.organizeImports.ruff": "explicit"
}
}
}
のような設定です。
Ruff自体のルールはpyproject.tomlへ書く
一方で、RuffそのもののLintルールやフォーマット設定はpyproject.tomlへまとめる方法がおすすめです。
例えば次のようにします。
[project]
requires-python = ">=3.11"[tool.ruff]
line-length = 88
[tool.ruff.lint]
select = [“E”, “F”, “I”, “UP”]
[tool.ruff.format]
quote-style = “double” indent-style = “space”
このように分けることで、
VSCode上の動作
→ .vscode/settings.json
Ruffのコード規約
→ pyproject.toml
という役割分担になります。
CLIやCI/CDでも同じRuff設定を利用しやすくなるのがメリットです。
Ruffが動かない場合の確認ポイント
Ruff拡張機能が有効になっているか確認する
VSCodeのExtensions画面からRuffを開き、拡張機能が有効になっているか確認します。
無効になっている場合は有効化します。
Pythonファイルとして認識されているか確認する
VSCode右下に表示されるLanguage Modeが次のようになっているか確認します。
Python
Pythonとして認識されていない場合、Ruffの機能が正しく動作しないことがあります。
CLI版Ruffのバージョンを確認する
Python環境へRuffをインストールしている場合は、次のコマンドを実行します。
ruff --version
バージョン情報が表示されれば、CLI版Ruffは利用できます。
Pythonインタープリターを確認する
仮想環境内にRuffをインストールしている場合は、VSCodeがそのPython環境を認識しているか確認します。
コマンドパレットから次を実行します。
Python: Select Interpreter
使用している.venvなどを選択します。
ただし、仮想環境内にRuffが見つからない場合でも、Ruff拡張機能はPATH上や拡張機能同梱版へフォールバックできるため、Pythonインタープリターが異なるだけで必ずRuffが動かなくなるわけではありません。
他のFormatterと競合していないか確認する
Black Formatterなどをインストールしている場合は、Python用のデフォルトFormatterを確認します。
Ruff Formatterを使用するなら、次のように設定します。
{
"[python]": {
"editor.defaultFormatter": "charliermarsh.ruff"
}
}
VSCodeでRuffを使うおすすめ構成
新規PythonプロジェクトならRuff＋Pylanceがシンプル
新しくPython開発環境を作るのであれば、次のような構成はシンプルで管理しやすいです。
VSCode
├─ Python
├─ Pylance
└─ Ruff
Ruffには、
Lint
Formatter
import整理
自動修正
を担当させます。
Pylanceには、
型解析
コード補完
定義ジャンプ
Hover情報
などを担当させます。
さらに、.vscode/settings.jsonにはVSCode固有の保存設定を書き、pyproject.tomlにはRuffのルールを書いておくと、プロジェクト全体を整理しやすくなります。
まとめ
VSCodeでRuffを設定する場合は、まずRuff拡張機能をインストールし、必要に応じてプロジェクト環境にもRuffを導入します。
VSCode側では、RuffをデフォルトFormatterに設定し、保存時のLint修正やimport整理を有効にすると便利です。
一方、Lintルールや対象Pythonバージョン、行の長さなどはpyproject.tomlにまとめると、VSCodeだけでなくCLIやCI/CDでも同じ設定を共有できます。
新規プロジェクトであれば、RuffにLint、Formatter、import整理をまとめ、Pylanceに型解析やコード補完を担当させる構成が分かりやすいでしょう。
以上、VSCodeでRuffを設定する方法についてでした。
最後までお読みいただき、ありがとうございました。
