LangChainをVSCodeで使うとインポートエラーが出る問題とその解決法（settings.json付き）

はじめに

クラウド事業部の大久保と申します。現在、PythonでLangChainやLangGraphのAgentアプリケーションを実装している中でVSCodeや仮想環境の整備に苦労したので、その中からLangChainのインポートについて記事にしました。

対象読者

VSCodeを利用してPythonでLangChainでプログラムを書き始めた皆様。

インポート課題

PythonでLangChain や LangGraph を使って開発していると、VSCode上で補完が効かない、importに赤線が出るといった困りごとが発生します。

⬆ ホバーしてインポートしたいのに😢

これは VSCode（正確には Pylance）が、LangChain 系モジュールの構造を深すぎてパッケージとして認識できていないことが原因です。

結論：settings.json を正しく書けば解決します

VSCode に「このモジュール、ちゃんと見に行ってね」と伝えるために、以下の2つの設定が重要です：

python.analysis.packageIndexDepths
python.analysis.extraPaths

さらに、Ruff や pytest、仮想環境などの周辺設定も含めて、実用性の高い .vscode/settings.json を用意しました

LangChain系のライブラリに対応したsettings.json

{
  // 仮想環境のパス（.venv を利用）
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",

  // LangChain系モジュールを認識させる
  "python.analysis.extraPaths": ["${workspaceFolder}/.venv/lib/python3.12/site-packages/"],
  "python.analysis.packageIndexDepths": [
    { "name": "langchain_core", "depth": 2 },
    { "name": "langchain", "depth": 2 },
    { "name": "langchain_community", "depth": 2 },
    { "name": "langgraph", "depth": 2 }
  ],
  "python.analysis.autoSearchPaths": true,
  "python.analysis.autoImportCompletions": true,
  "python.autoComplete.extraPaths": [
    "${workspaceFolder}/.venv/lib/python3.12/site-packages/langchain_core"
  ],

  // フォーマッター（Ruffを使用）
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "charliermarsh.ruff",

  // Ruff設定（VSCode拡張必須）
  "ruff.enable": true,
  "ruff.lineLength": 100,
  "ruff.importStrategy": "fromEnvironment",
  "ruff.interpreter": ["${workspaceFolder}/.venv/bin/python"],
  "ruff.path": ["${workspaceFolder}"],

  // pytest設定
  "python.testing.pytestEnabled": true,
  "python.testing.unittestEnabled": false,
  "python.testing.pytestArgs": ["tests"]
}

なぜこれで解決するのか？

理由：packageIndexDepths が LangChain の深い構造を認識させる

LangChain はサブパッケージが深くネストされており、普通にインストールしただけでは補完や警告がうまく働きません。

この設定により、VSCode がパッケージの中を2階層以上深く掘って見てくれるようになります。

settings.jsonのポイント

extraPaths によって仮想環境の site-packages を明示

LangChain を .venv にインストールしている場合、VSCodeが補完対象に含めるためには明示的に extraPaths を書く必要があります。
ネストの深いライブラリを"python.analysis.packageIndexDepths"にて指定することで読み込みかのう。

Ruff や pytest にも対応

フォーマッターを Ruff、テストランナーを pytest に設定することで、補完・静的解析・実行すべてがスムーズに回るようになります。

注意点

この設定は VSCode内での補完・警告の解決を目的としています。実行時の ImportError などが発生する場合は、別途 PYTHONPATH の設定や pyproject.toml での調整が必要になることがあります。

Ruffについて

Ruff は、Python用の超高速Lint＆フォーマッターです。 Flake8、isort、pylint、mypy などの役割を1つにまとめてくれるツールで、Rustで書かれているため非常に高速なのが特徴です。

設定もシンプルで、VS Codeと組み合わせれば、保存時に自動でコードチェック＆整形までしてくれる便利ツールです。

VSCodeのプラグイン追加

プロジェクトへの導入手順

公式のガイドをご参考にください。ガイドの前提としてはuvを利用したpyproject.tomlを利用したプロジェクト管理が前提になっているのでご利用のpython環境でuvだけ入れて下さい。

pip install uv

docs.astral.sh

まとめ

LangChainやLangGraphは便利ですが、その構造の深さから、VSCode上で補完や解析がうまく動かないことがあります。

その際は、今回紹介したように settings.json に以下の設定を入れることで簡単に解決できます：

extraPaths → site-packages を認識させる
packageIndexDepths → LangChainを深く見させる
Ruff や pytest の設定も一緒に整える

VSCodeでLangChainを快適に扱うための設定として、ぜひ参考にしてください！

おわりに

私達クラウド事業部はクラウド技術を活用したSI/SESのご支援をしております。

www.ap-com.co.jp

また、一緒に働いていただける仲間も募集中です！ご興味持っていただけましたらぜひお声がけください。

APC 技術ブログ

株式会社エーピーコミュニケーションズの技術ブログです。