Pylanceのインポートエラーを理解する
Import "module_name" could not be resolved from source file というエラーは、VS CodeでPylance言語サーバーを使用しているPython開発者が頻繁に遭遇する問題です。これは、コード自体はターミナルで実際に正しく実行できる場合でも、Pylance（静的型チェッカー）がインポートされたモジュールのソースコードを見つけられず、IntelliSense、型チェック、ナビゲーション機能を提供できないことを示しています。
# エディタにエラーが表示される例
import requests # Error: Import "requests" could not be resolved from source file
from my_local_module import helper # Error: Import "my_local_module" could not be resolved from source file
このエラーは、Pylanceが特定のパスのセット内でモジュールを検索するために発生します。VS Code内で環境が正しく構成されていない場合、インポートをディスク上の物理ファイルにマッピングできなくなります。
ステップ 1: Pythonインタープリターを確認する
最も一般的な原因は、VS Codeがパッケージのインストール先とは異なるPythonインタープリターを使用していることです。例えば、仮想環境（venv）に pandas をインストールしたのに、VS CodeがグローバルなシステムPythonを使用している場合などが考えられます。
Ctrl + Shift + P(Windows/Linux) またはCmd + Shift + P(macOS) を押してコマンドパレットを開きます。- Python: インタープリターを選択 (Select Interpreter) と入力し、選択します。
- 仮想環境に対応するインタープリターを選択します。通常、
./venv/bin/pythonや('venv': venv)のように表示されます。
Pylanceが再インデックスを行うまで数秒待ちます。赤い波線が消えれば、インタープリターの不一致が原因だったことになります。
ステップ 2: ローカルモジュールの追加パスを構成する
すべてのソースコードを src/ ディレクトリに配置するなど、標準的ではないプロジェクト構造で作業している場合、Pylanceはそのフォルダー内を検索対象として認識していない可能性があります。
これを修正するには、settings.json ファイルを介して、これらの追加ディレクトリをPylanceに伝える必要があります。
- プロジェクトのルートにある
.vscode/settings.jsonファイルを作成または開きます。 python.analysis.extraPaths設定を追加します。
{
"python.analysis.extraPaths": [
"./src",
"./path/to/your/custom/modules"
]
}
これにより、Language Server Protocol (LSP) がモジュール定義を検索する際に、これらのディレクトリを含めるようになります。
ステップ 3: ワークスペースのルートを確認する
Pylanceは、現在VS Codeで開いているフォルダーを基準にパスを解決します。複数のサブプロジェクトを含む「親」フォルダーを開いている場合、Pylanceがインポートルートを正しく認識できないことがあります。
解決策: 常に特定のプロジェクトのルートフォルダーをVS Codeのワークスペースとして開いてください。/projects/my_python_app/ のような構造の場合、projects フォルダーではなく my_python_app を直接開きます。
ステップ 4: PYTHONPATHに .env ファイルを使用する
実行時にモジュールを見つけるために PYTHONPATH 環境変数に依存している場合があります。.env ファイルを使用すれば、Pylanceでもこれらの設定を反映させることができます。
- プロジェクトのルートに
.envという名前のファイルを作成します。 - ソースディレクトリをパスに追加します。
PYTHONPATH=src
.vscode/settings.jsonで、envファイルが読み込まれるように設定します。
{
"python.envFile": "${workspaceFolder}/.env"
}
ステップ 5: Pylance言語サーバーをリフレッシュする
特に大量の pip install を行った後など、Pylanceの内部インデックスが古くなったり破損したりすることがあります。サーバーを再起動することで、site-packagesの再スキャンを強制できます。
- コマンドパレットを開きます (
Ctrl + Shift + P)。 - Python: 言語サーバーを再起動 (Restart Language Server) と入力します。
検証: 修正が機能したことを確認する方法
問題が適切に解決されたことを確認するために、以下のチェックを行ってください。
- 視覚的な確認:
import文の下にある赤い波線が消えているはずです。 - 定義へ移動: インポートされたモジュール名の上にマウスを置き、
Ctrl(またはCmd) を押しながらクリックします。VS Codeでそのモジュールのソースファイルが開けば、パスの解決が機能しています。 - IntelliSense: モジュール名の後にドットを入力します (例:
module_name.)。関数やクラスのリストが表示されれば、Pylanceは正常にモジュールをインデックスしています。
まとめのヒント
- 依存関係を分離するために、常に仮想環境 (
python -m venv venv) を使用してください。 - パッケージをインストールした直後の場合は、エラーだと判断する前に、Pylanceがインデックスを作成するまで少し時間を置いてください。
- 型チェックの構成に
pyrightconfig.jsonやpyproject.tomlを使用している場合は、それらがVS Codeの設定を上書きする可能性があるため、内容を確認してください。