Zenn
📚

vscode(cursor)のPylanceのインポート解決

2025/02/13に公開
VS Code
pyenv
poetry
Cursor
tech

PythonプロジェクトをVSCodeで開発していると、プロジェクト固有のディレクトリ構造や仮想環境（venv）の設定が適切でないと、Pylanceがモジュールのインポートを正しく解決できず、補完機能や型チェックがうまく働かないことがある。ここでは、extraPathsの設定とautoImportCompletionsの有効化、さらにvenvの設定について解説する。
cursorでも同様の設定で解決可能。

1.仮想環境（venv）の設定：pyenv と poetry を利用

a. pyenvでPythonのバージョン管理

  1. pyenvのインストール
    まだインストールしていない場合は、pyenvの公式GitHubリポジトリの手順に従い、pyenvをインストールする。

  2. 必要なPythonバージョンのインストール
    例として、Python 3.9.7 をインストールする場合、以下のコマンドを実行。

pyenv install 3.9.7
  1. プロジェクトディレクトリでローカルバージョンを設定
    プロジェクトフォルダ内で、使用するPythonバージョンをローカルに設定。
pyenv local 3.13.1

b. poetryでプロジェクト管理と仮想環境の作成

  1. poetryのインストール
    poetryが未インストールの場合、以下のコマンドでインストール。
curl -sSL https://install.python-poetry.org | python3 -

2.プロジェクトの初期化
プロジェクトディレクトリで以下のコマンドを実行し、
.toml を作成します。対話式でプロジェクト情報の入力が求められます。

poetry init
  1. 仮想環境をプロジェクト内に作成する設定
    VSCodeとの連携をスムーズにするため、以下のコマンドを実行して仮想環境をプロジェクトディレクトリ内に作成するよう設定する。
poetry config virtualenvs.in-project true

これにより、仮想環境がプロジェクトフォルダ内（通常は .venv ディレクトリ）に作成され、VSCodeが簡単に認識できるようになる。

  1. 依存関係の追加
    プロジェクトに必要なライブラリを追加する際は、次のようにコマンドを実行。
poetry add <package_name>
  1. 仮想環境の自動作成と管理
    poetryは自動的に仮想環境を作成して管理します。既存の依存関係をインストールするには、以下のコマンドを実行。
poetry install

また、仮想環境の詳細情報は以下のコマンドで確認できる。

poetry env info
  1. VSCodeでpoetry管理の仮想環境を利用する
    VSCode上で正しいPythonインタープリターを使用するため、コマンドパレット（Ctrl+Shift+P または Cmd+Shift+P）を開き、Python: Select Interpreter と入力。リストから、poetryが作成した仮想環境を選択。

※ コマンドラインから poetry shell を実行することで、仮想環境に入ることも可能。

2. ソースコードの場所を明示する設定

プロジェクト内のソースコードが ./src に配置されている場合、Pylanceに対してそのパスを追加する必要があります。以下のように、.vscode/settings.json に設定を記述します。

{
    "python.analysis.extraPaths": [
        "${workspaceFolder}/src"
    ],
    "python.analysis.autoImportCompletions": true
}

  • python.analysis.extraPaths
    ここでは ${workspaceFolder}/src を指定することで、現在のワークスペース内の src ディレクトリをインポート対象として追加しています。これにより、src 内のモジュールをインポートする際、Pylanceが正しく解決できるようになります。

  • python.analysis.autoImportCompletions
    このオプションを有効にすることで、インポート候補の自動補完が強化され、モジュール名やパスの入力がスムーズになります。

Discussion