Pylanceのインポート解決エラーを修正する方法

問題の概要

Visual Studio Code (VS Code) でPython開発を行う際、Pylance拡張機能が特定のモジュールやパッケージを認識できない「Import could not be resolved」エラーが発生することがあります。この問題は仮想環境を使用している場合や、プロジェクト構造が複雑な場合に特に頻発します。

この問題が発生すると、以下のような症状が見られます：

• コードの実行自体は正常に動作するが、エディター上でインポートエラーが表示される
• インテリセンス（コード補完）が機能しない
• 型チェックや静的解析が正しく行えない

主な解決策

1. Pythonインタプリタの正しい設定

最も基本的かつ効果的な解決方法は、VS Codeが正しいPythonインタプリタを使用していることを確認することです。

コマンドパレットを使用

# Ctrl+Shift+P でコマンドパレットを開く
# 「Python: Select Interpreter」を選択
# 仮想環境のPythonインタプリテァを選択

settings.jsonで直接指定

{
  "python.defaultInterpreterPath": "./server/venv/Scripts/python.exe"
}

仮想環境の確認方法

ターミナルで以下のコマンドを実行し、正しい環境がアクティブになっているか確認します：

python -c "import sys; print(sys.executable)"

2. キャッシュのクリアとウィンドウの再読み込み

Pylanceのキャッシュ問題が原因の場合、以下の手順で解決できます：

1. Ctrl+Shift+P でコマンドパレットを開く
2. Python: Clear Cache and Reload Window を実行
3. または Developer: Reload Window を実行

3. 仮想環境のアクティベーション

ターミナルからVS Codeを起動する場合、事前に仮想環境をアクティブにしておくことが重要です：

venvの場合

# 仮想環境のアクティベーション
source server/venv/bin/activate  # Linux/macOS
server\venv\Scripts\activate     # Windows

# その後でVS Codeを起動
code .

condaの場合

# Conda環境のアクティベーション
conda activate myenv

# その後でVS Codeを起動
code .

詳細なトラブルシューティング

依存関係の再インストール

仮想環境内で正しくパッケージがインストールされているか確認します：

# 仮想環境をアクティブにした後
cd server
pip install -r requirements.txt

Pylanceの追加パス設定

場合によっては、Pylanceに追加のパスを指定する必要があります：

1. Ctrl+, で設定を開く
2. @ext:ms-python.vscode-pylance で検索
3. Python › Analysis: Extra Paths 設定を見つける
4. サイトパッケージのパスを追加（pip --version で確認可能）

プロジェクト構造の最適化

VS Codeはルートディレクトリの仮想環境を期待します。複雑なプロジェクト構造の場合は、適切なワークスペースを設定しましょう：

プロジェクトルート/
├── .vscode/
│   └── settings.json
├── client/          # Reactフロントエンド
└── server/          # Flaskバックエンド
    ├── venv/        # 仮想環境
    ├── app/
    └── requirements.txt

環境別の注意点

Windows環境の場合

Windowsではパス区切り文字や実行権限に注意が必要です：

# 仮想環境内でのインストール
.\server\venv\Scripts\python -m pip install -r requirements.txt

Conda環境を使用する場合

Condaとpipの混合使用は問題を引き起こすことがあります：

# 可能な限りcondaでパッケージをインストール
conda install package-name

# または、明示的にpipを指定
conda install pip
pip install package-name

asdfなどのバージョンマネージャーを使用する場合

which python で実際に使用されているPythonインタプリタのパスを確認し、VS Codeでそのパスを指定します。

予防策

1. 一貫した環境設定: プロジェクトごとに独立した仮想環境を使用する
2. 設定ファイルの共有: .vscode/settings.json をバージョン管理に含める
3. 定期的なキャッシュクリア: 定期的にPylanceキャッシュをクリアする
4. 拡張機能の更新: Python拡張機能とPylanceを最新版に保つ

注意

ネットワークドライブや共有フォルダー上でプロジェクトを開いている場合、パス解決の問題が発生する可能性があります。可能な限りローカルディレクトリで作業してください。

まとめ

Pylanceのインポート解決問題は、主に以下の点を確認することで解決できます：

1. 正しいPythonインタプリタの選択
2. 仮想環境の適切な設定とアクティベーション
3. Pylanceキャッシュの定期的なクリア
4. プロジェクト構造と設定の最適化

これらの対策を実施しても問題が解決しない場合は、VS CodeのPython拡張機能を再インストールするか、問題の再現手順を詳細に記録して公式イシュートラッカーに報告してください。