MENU
contact

VSCodeでmypyを設定して利用する方法について

VSCode

採用はこちら

VSCodeでPythonを開発する際、mypyを導入すると、コードを実行する前に型の不整合を検出できます。

Pythonは動的型付け言語ですが、型アノテーションを付けることで、mypyによる静的型チェックを利用できます。

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

def add(a: int, b: int) -> int:
    return a + b


result = add("10", "20")

add() の引数には int が指定されていますが、実際には文字列を渡しています。

mypyを実行すると、このような型の不整合をプログラム実行前に検出できます。

VSCodeでは、Microsoftが提供している「Mypy Type Checker」拡張機能を利用すると、エディター上でmypyの診断結果を確認できます。

目次

VSCodeでmypyを使うために必要なもの

VSCodeでmypyを利用する場合は、主に次の環境を用意します。

VSCode
├─ Python拡張機能
├─ Mypy Type Checker拡張機能
├─ Python仮想環境
│  └─ mypy
└─ Pythonプロジェクト
   ├─ .venv/
   ├─ pyproject.toml
   └─ src/

特に実務では、次の組み合わせがおすすめです。

Python拡張機能
+
Mypy Type Checker
+
プロジェクト専用の仮想環境
+
pyproject.toml

mypyのルールを pyproject.toml にまとめておけば、VSCodeだけでなく、ターミナルやCIでも同じ設定を利用できます。

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

まず、VSCodeにMicrosoft製のPython拡張機能をインストールします。

拡張機能画面を開く

WindowsやLinuxでは、次のショートカットを使用します。

Ctrl + Shift + X

macOSでは次のショートカットです。

Cmd + Shift + X

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

Python拡張機能では、Pythonインタープリターの選択、コード実行、デバッグなどの機能を利用できます。

Mypy Type Checkerをインストールする

続いて、mypyをVSCode上で利用するための拡張機能をインストールします。

Mypy Type Checkerを検索する

拡張機能画面で、次の名前を検索します。

Mypy Type Checker

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

拡張機能IDは次のとおりです。

ms-python.mypy-type-checker

Mypy Type Checkerを導入すると、Pythonファイルの型チェック結果をVSCodeの「問題」パネルなどで確認できるようになります。

Pythonの仮想環境を作成する

Pythonプロジェクトでは、mypyを含むパッケージをプロジェクトごとに管理するため、仮想環境を利用するのがおすすめです。

venvで仮想環境を作成する

プロジェクトフォルダでVSCodeのターミナルを開きます。

WindowsやLinuxでは、次のショートカットを利用できます。

Ctrl + `

ターミナルで次のコマンドを実行します。

python -m venv .venv

環境によっては、次のように python3 を使用します。

python3 -m venv .venv

作成後は、次のようなディレクトリ構成になります。

my-project/
├─ .venv/
├─ src/
└─ pyproject.toml

VSCodeから仮想環境を作成する方法

VSCodeでは、コマンドパレットから仮想環境を作成することもできます。

コマンドパレットを開き、

Python: Create Environment

を実行します。

VenvやCondaなどを選択して環境を作成できます。

VSCodeでPythonインタープリターを選択する

仮想環境を作成したら、VSCodeに使用するPython環境を指定します。

Python: Select Interpreterを実行する

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

WindowsやLinuxでは、

Ctrl + Shift + P

macOSでは、

Cmd + Shift + P

です。

次のコマンドを検索します。

Python: Select Interpreter

作成した .venv のPythonを選択します。

VSCodeでは、ワークスペース内の .venv や venv などの仮想環境が検出されます。

mypyを仮想環境にインストールする

続いて、プロジェクトの仮想環境にmypyをインストールします。

python -m pip install mypy

インストール後、次のコマンドで確認できます。

python -m mypy --version

または、

mypy --version

でも確認できます。

Mypy Type Checkerにはmypyが同梱されている

Mypy Type Checker拡張機能には、mypyがバンドルされています。

そのため、VSCode上で型チェックするだけであれば、必ずしも仮想環境へmypyをインストールしなければならないわけではありません。

ただし、実務ではプロジェクト側にもmypyをインストールしておく方法がおすすめです。

理由は、次の環境で同じmypyバージョンを利用しやすくなるためです。

VSCode
CLI
CI/CD
他の開発者の環境

仮想環境内のmypyをVSCodeで利用する

プロジェクトにインストールしたmypyを優先的に利用したい場合は、VSCodeの設定を変更します。

settings.jsonを設定する

.vscode/settings.json に次の設定を記述します。

{
    "mypy-type-checker.importStrategy": "fromEnvironment"
}

fromEnvironment を指定すると、選択されているPython環境からmypyを利用する構成になります。

プロジェクトごとにmypyのバージョンを固定している場合に適しています。

mypyが動作するか確認する

実際に型エラーを発生させて、mypyが正常に動いているか確認してみましょう。

型エラーがあるコードを作成する

次のコードを作成します。

def greet(name: str) -> str:
    return "Hello " + name


greet(123)

greet() の引数は str と指定されています。

しかし、

greet(123)

では整数を渡しています。

mypyが正常に動作していれば、VSCode上で型エラーが表示されます。

問題パネルを確認する

VSCodeでは、次のショートカットで「問題」パネルを開けます。

Ctrl + Shift + M

mypyの診断結果がここに表示されます。

ターミナルからmypyを実行する

VSCodeの拡張機能だけでなく、ターミナルから直接mypyを実行することもできます。

ファイル単位でチェックする

python -m mypy main.py

または、

mypy main.py

と実行します。

ディレクトリ単位でチェックする

たとえば、src ディレクトリ全体をチェックする場合は次のとおりです。

python -m mypy src

プロジェクト全体を型チェックしたい場合、CLIでの実行は非常に重要です。

pyproject.tomlでmypyを設定する

mypyはコマンドラインオプションだけでなく、設定ファイルから各種ルールを読み込めます。

代表的な設定ファイルには次のものがあります。

mypy.ini
.mypy.ini
pyproject.toml
setup.cfg

現在のPythonプロジェクトでは、複数の開発ツールの設定をまとめやすい pyproject.toml が使いやすい選択肢です。

基本的な設定例

[tool.mypy]
python_version = "3.13"
warn_return_any = true
warn_unused_configs = true
check_untyped_defs = true

python_version は、実際にプロジェクトが対象としているPythonバージョンに合わせます。

Python 3.12を対象とする場合は、次のようにします。

[tool.mypy]
python_version = "3.12"

単純にPCへインストールされているPythonのバージョンを書くのではなく、プロジェクトがサポートするPythonバージョンを指定するのが基本です。

mypyのstrictモードを利用する

より厳格な型チェックを行いたい場合は、strict を利用できます。

[tool.mypy]
strict = true

strictは複数の厳格設定をまとめて有効化する

strict = true は、1種類の特別なチェックモードというより、複数の厳格なmypyオプションをまとめて有効化するための設定です。

たとえば、型アノテーションが不足しているコードなどをより厳しくチェックできます。

def add(a, b):
    return a + b

新規プロジェクトで最初から型安全性を高めたい場合には便利です。

一方、既存の大規模プロジェクトに突然導入すると大量のエラーが発生する可能性があります。

その場合は、段階的にルールを厳しくしていく方が現実的です。

mypyでよく使われる設定

mypyでは、目的に応じてさまざまな設定を利用できます。

check_untyped_defs

check_untyped_defs = true

型アノテーションが十分に付いていない関数でも、関数内部をチェックするための設定です。

既存コードへmypyを導入するときにも使いやすい設定です。

disallow_untyped_defs

disallow_untyped_defs = true

型アノテーションのない関数定義をエラーとして扱います。

たとえば、次のコードが対象になります。

def add(a, b):
    return a + b

次のように型を明示します。

def add(a: int, b: int) -> int:
    return a + b

比較的厳しい設定なので、既存プロジェクトでは段階的に導入するのがおすすめです。

warn_return_any

warn_return_any = true

関数の戻り値が Any になってしまうケースを検出しやすくします。

Any が増えすぎるとmypyによる型チェックの効果が弱くなるため、有効な設定です。

warn_unused_configs

warn_unused_configs = true

利用されていないmypy設定を検出しやすくします。

設定ミスの発見にも役立ちます。

warn_unused_ignores

warn_unused_ignores = true

不要になった次のような記述を検出できます。

# type: ignore

型エラーが解消したあとも type: ignore が残り続けることを防ぎやすくなります。

外部ライブラリの型情報がない場合

利用しているライブラリによっては、型情報が提供されていないことがあります。

その場合、mypyから次のようなエラーが表示されることがあります。

Skipping analyzing ...
Missing library stubs ...

特定のライブラリだけ無視する

pyproject.toml では、モジュールごとの設定を記述できます。

[[tool.mypy.overrides]]
module = "some_library.*"
ignore_missing_imports = true

複数のモジュールを対象にする場合は次のように記述できます。

[[tool.mypy.overrides]]
module = [
    "some_library",
    "some_library.*",
    "another_library",
    "another_library.*"
]
ignore_missing_imports = true

ignore_missing_importsの全体適用には注意する

次のような設定も可能です。

[tool.mypy]
ignore_missing_imports = true

ただし、すべてのライブラリの未解決importが無視されるため、本来検出できる型エラーまで見逃しやすくなります。

可能であれば、問題があるライブラリだけを overrides で指定する方法がおすすめです。

VSCodeでプロジェクト全体をチェックする

Mypy Type Checkerでは、チェック対象の範囲を設定できます。

fileモード

基本的には、現在開いているファイルを中心にチェックする設定です。

{
    "mypy-type-checker.reportingScope": "file"
}

小規模なプロジェクトや、VSCodeの負荷を抑えたい場合に適しています。

workspaceモード

ワークスペース全体を対象にしたい場合は、次のように設定します。

{
    "mypy-type-checker.reportingScope": "workspace"
}

ただし、大規模なプロジェクトでは解析に時間がかかったり、CPU負荷が高くなったりする可能性があります。

最初は file で運用し、必要に応じて workspace へ変更する方法が扱いやすいでしょう。

dmypyを利用して高速化する

mypyには dmypy と呼ばれるデーモンモードがあります。

mypyを何度も起動するのではなく、常駐プロセスを利用することで、繰り返し実行時の高速化が期待できます。

preferDaemonを有効にする

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

{
    "mypy-type-checker.preferDaemon": true
}

継続的に型チェックする環境では、パフォーマンス改善につながる場合があります。

dmypyで問題が起きた場合

環境や拡張機能のバージョンによっては、dmypy使用時に問題が発生することがあります。

その場合は、次のように通常実行へ戻して動作を確認します。

{
    "mypy-type-checker.preferDaemon": false
}

mypy関連のエラーが突然発生した場合の切り分け方法として覚えておくと便利です。

Mypy Type Checkerに追加オプションを渡す

VSCode側からmypyへ追加オプションを指定することもできます。

{
    "mypy-type-checker.args": [
        "--show-error-codes"
    ]
}

ただし、型チェックそのものに関する設定は、できるだけ pyproject.toml にまとめる方がおすすめです。

VSCodeとmypyの設定を分ける

管理しやすい構成は次のとおりです。

VSCode固有の設定
→ .vscode/settings.json

mypyそのものの型チェックルール
→ pyproject.toml

たとえば、show_error_codes は次のように pyproject.toml に書けます。

[tool.mypy]
show_error_codes = true

こうすることで、VSCodeとCLI、CIで同じ設定を共有できます。

おすすめのsettings.json

まずは次のようなシンプルな設定から始めるのがおすすめです。

{
    "mypy-type-checker.importStrategy": "fromEnvironment",
    "mypy-type-checker.reportingScope": "file"
}

プロジェクト全体を継続的にチェックしたい場合は、次のような構成も利用できます。

{
    "mypy-type-checker.importStrategy": "fromEnvironment",
    "mypy-type-checker.reportingScope": "workspace",
    "mypy-type-checker.preferDaemon": true
}

問題が発生した場合は、まず preferDaemon を false に変更して切り分けるとよいでしょう。

おすすめのpyproject.toml

初めてmypyを導入する場合は、あまり厳しくしすぎない設定から始める方法がおすすめです。

[tool.mypy]
python_version = "3.13"

check_untyped_defs = true
warn_return_any = true
warn_unused_configs = true
warn_unused_ignores = true

show_error_codes = true
pretty = true

プロジェクトの型アノテーション整備が進んだら、次の設定を追加できます。

disallow_untyped_defs = true

さらに厳密な型管理が必要な場合は、

strict = true

の導入を検討します。

srcディレクトリ構成でmypyを利用する

Pythonプロジェクトでは、ソースコードを src 配下に置く構成もよく利用されます。

project/
├─ .venv/
├─ .vscode/
│  └─ settings.json
├─ src/
│  └─ myapp/
│     ├─ __init__.py
│     └─ main.py
├─ tests/
└─ pyproject.toml

この場合、次のようにmypyを実行できます。

python -m mypy src

CIでも同じコマンドを利用できます。

VSCode
→ mypy

ローカルターミナル
→ python -m mypy src

CI
→ python -m mypy src

このように統一すると、開発環境による型チェック結果の違いを減らせます。

VSCodeでmypyが動かない場合の対処法

mypyが正常に動作しない場合は、いくつかのポイントを確認します。

Pythonインタープリターを確認する

まず、

Python: Select Interpreter

を実行して、目的の .venv が選択されているか確認します。

違うPython環境が選択されていると、インストールしたmypyやライブラリが見つからない場合があります。

mypyがインストールされているか確認する

ターミナルで次を実行します。

python -m mypy --version

エラーになる場合は、mypyをインストールします。

python -m pip install mypy

importStrategyを確認する

プロジェクト環境内のmypyを使いたい場合は、次の設定を確認します。

{
    "mypy-type-checker.importStrategy": "fromEnvironment"
}

Mypyサーバーを再起動する

コマンドパレットから、

Mypy: Restart Server

を実行すると、Mypy Type Checkerを再起動できます。

設定変更後に挙動がおかしい場合にも有効です。

ログを確認する

問題が解決しない場合は、Mypy Type Checkerのログを確認します。

詳細ログを取得したい場合は、次の設定を利用できます。

{
    "mypy-type-checker.trace.server": "verbose"
}

エラー原因の切り分けに役立ちます。

Pylanceとmypyの違い

VSCodeでPythonを使っていると、Pylanceとmypyの違いが分かりにくいことがあります。

両者には一部重なる機能があります。

Pylanceの役割

Pylanceは、VSCode向けのPython言語サーバーです。

主に次の機能を提供します。

コード補完
型推論
型チェック
定義ジャンプ
参照検索
ホバー情報

PylanceはPyrightをベースとしており、エディター上でリアルタイムに型解析を行えます。

mypyの役割

mypyは、IDEに依存せず利用できる静的型チェッカーです。

次のような環境で利用できます。

VSCode
ターミナル
Gitのpre-commit
CI/CD

特に、CLIやCIでも同じルールで型チェックできることが大きな特徴です。

Pylanceとmypyは併用できる

両者を同時に利用することも可能です。

VSCode
├─ Pylance
│  ├─ 補完
│  ├─ 定義ジャンプ
│  ├─ 型推論
│  └─ 型チェック
│
└─ Mypy Type Checker
   └─ mypyによる型チェック

ただし、似た型エラーが重複して表示されることもあります。

そのため、

Pylance
→ エディター上の補完やリアルタイム解析

mypy
→ プロジェクトとして正式に採用する型チェック

のように役割を整理すると管理しやすくなります。

保存するたびにmypyを手動実行する必要はない

Mypy Type Checkerを導入していれば、VSCode上で型エラーを確認できます。

そのため、コードを少し変更するたびに、

python -m mypy main.py

を手動実行する必要はありません。

一方で、コミット前やCIでは、プロジェクト全体を次のように確認すると安全です。

python -m mypy src

開発中とCIで役割を分けると、効率よく運用できます。

CIでもmypyを実行する

VSCodeだけでmypyを利用している場合、開発者によって拡張機能の有無や設定が異なる可能性があります。

そのため、チーム開発ではCIでもmypyを実行するのがおすすめです。

python -m mypy src

開発フローは、たとえば次のようになります。

コードを書く
↓
VSCodeでmypyのエラーを確認
↓
コミット
↓
CIでpython -m mypy srcを実行
↓
型エラーがなければマージ

これにより、開発者個人のVSCode設定だけに依存しない型チェックが可能になります。

VSCodeでmypyを利用するおすすめ構成

最終的には、次のような構成にすると管理しやすくなります。

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

settings.json

{
    "mypy-type-checker.importStrategy": "fromEnvironment",
    "mypy-type-checker.reportingScope": "file"
}

pyproject.toml

[tool.mypy]
python_version = "3.13"

check_untyped_defs = true
warn_return_any = true
warn_unused_configs = true
warn_unused_ignores = true

show_error_codes = true
pretty = true

mypyのインストール

python -m pip install mypy

VSCodeでPython環境を選択

Python: Select Interpreter
↓
.venvを選択

CLIでプロジェクト全体をチェック

python -m mypy src

VSCodeでmypyを使うときのポイント

VSCodeでmypyを利用するうえで重要なのは、VSCodeだけに設定を閉じ込めないことです。

型チェックのルールは、

pyproject.toml

にまとめ、VSCodeはそのmypyを利用する役割にするのがおすすめです。

この構成にすると、

VSCode
ローカルのターミナル
CI/CD

で同じ型チェックルールを利用できます。

また、既存プロジェクトでは最初から strict = true にするのではなく、

check_untyped_defs
warn_return_any
warn_unused_ignores

などから段階的に導入すると、無理なくmypyを定着させやすくなります。

VSCode上でリアルタイムに問題を確認しながら、最終的にはCLIやCIでも python -m mypy を実行する構成にすると、Pythonコードの型安全性を効率よく高められます。

以上、VSCodeでmypyを設定して利用する方法についてでした。

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

VSCode
よかったらシェアしてね！
  • URLをコピーしました！
  • URLをコピーしました！

関連記事

  1. ホーム
  2. VSCode
  3. VSCodeでmypyを設定して利用する方法について
目次