🦔

Poetryで作成したPythonプロジェクトをVSCode/Cursor等でエラーなく開く方法

に公開
Python
VS Code
linter
error
Cursor
tech

Poetryで作成したPythonプロジェクトをVSCodeやCursorで開いたとき、importエラーやモジュールが見つからないエラーが発生したことはありませんか？
これは、エディタがPoetryの仮想環境を正しく認識できていないことが原因です。

💡 前提知識
この記事を読む前に、Poetryの基本的な使い方について以下の記事を確認することをお勧めします

https://zenn.dev/goshawk/articles/974679c38d7268

今回は、PoetryプロジェクトをVSCode/Cursorで正しく設定し、エラーを解消する方法を紹介します。

🚨 問題：Poetryプロジェクトでよくあるエラー

Poetryで作成したプロジェクトをVSCode/Cursorで開くと、以下のようなエラーが発生することがあります：

  • importエラー: インストールしたライブラリが見つからない
  • モジュール解決エラー: プロジェクト内のモジュールが認識されない
  • 型チェックエラー: Pylanceが正しいPython環境を認識できない
  • パス解決エラー: 相対インポートが正しく動作しない

なぜ起きるのか

Poetryは独自の仮想環境管理システムを持っており、デフォルトでは以下の場所に仮想環境を作成します：

  • macOS/Linux: ~/Library/Caches/pypoetry/virtualenvs/ (macOS)
  • Windows: %APPDATA%\pypoetry\virtualenvs\

VSCode/Cursorは、この仮想環境の場所を自動で認識できないため、エラーが発生します。

🆕 解決策：プロジェクト内仮想環境の設定

Poetryの仮想環境をプロジェクト内に作成することで、エディタが正しく認識できるようになります。

手順1：プロジェクト内仮想環境の設定

1. Poetry設定の確認

# 現在の設定を確認
poetry config --list

# 重要な設定項目
# virtualenvs.in-project = false  # これが問題の原因
# virtualenvs.path = "{cache-dir}/virtualenvs"  # デフォルトの場所

2. プロジェクト内仮想環境の有効化

# プロジェクト内に仮想環境を作成するように設定
poetry config virtualenvs.in-project true

# または、プロジェクト固有の設定として
poetry config virtualenvs.in-project true --local

3. 既存の仮想環境の削除

# 既存の仮想環境を削除
poetry env remove python

# または、手動で削除
rm -rf ~/Library/Caches/pypoetry/virtualenvs/プロジェクト名-*

4. 仮想環境の再作成

# 依存関係を再インストール
poetry install

# 仮想環境の情報を確認
poetry env info

手順2：VSCode/Cursorでの設定

1. Python拡張機能のインストール

VSCode/Cursorで以下の拡張機能をインストール：

  • Python (Microsoft)
  • Pylance (Microsoft)

2. Python環境の選択

# 1. Command Paletteを開く (Cmd+Shift+P / Ctrl+Shift+P)
# 2. "Python: Select Interpreter" を選択
# 3. .venv/bin/python を選択

3. ワークスペース設定の追加

.vscode/settings.jsonファイルを作成：

{
    "python.defaultInterpreterPath": "./.venv/bin/python",
    "python.terminal.activateEnvironment": true,
    "python.analysis.extraPaths": [
        "./src",
        "./tests"
    ],
    "python.linting.enabled": true,
    "python.linting.pylintEnabled": false,
    "python.linting.flake8Enabled": true,
    "python.formatting.provider": "black"
}

🔄 実践的なセットアップ手順

実際のプロジェクトで使える、完全なセットアップ手順を紹介します。

1. 新しいPoetryプロジェクトの作成

# 新しいプロジェクトを作成
poetry new my-python-app
cd my-python-app

# プロジェクト内仮想環境を有効化
poetry config virtualenvs.in-project true --local

# 依存関係を追加
poetry add requests
poetry add --group dev pytest black flake8

2. プロジェクト構造の確認

my-python-app/
├── pyproject.toml          # Poetry設定
├── poetry.toml            # プロジェクト固有設定
├── .venv/                 # 仮想環境（プロジェクト内）
├── my_python_app/         # ソースコード
│   ├── __init__.py
│   └── main.py
├── tests/                 # テストコード
│   ├── __init__.py
│   └── test_main.py
└── .vscode/              # VSCode設定
    └── settings.json

3. VSCode/Cursorでの設定

3.1 プロジェクトを開く

# VSCode/Cursorでプロジェクトを開く
code .  # VSCode
# または
cursor .  # Cursor

3.2 Python環境の選択

  1. Command Paletteを開く (Cmd+Shift+P / Ctrl+Shift+P)
  2. "Python: Select Interpreter" を選択
  3. .venv/bin/python を選択

3.3 ワークスペース設定の作成

.vscode/settings.jsonを作成：

{
    "python.defaultInterpreterPath": "./.venv/bin/python",
    "python.terminal.activateEnvironment": true,
    "python.analysis.extraPaths": [
        "./my_python_app",
        "./tests"
    ],
    "python.linting.enabled": true,
    "python.linting.flake8Enabled": true,
    "python.formatting.provider": "black",
    "python.testing.pytestEnabled": true,
    "python.testing.pytestArgs": [
        "tests"
    ],
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
        "source.organizeImports": true
    }
}

4. 動作確認

4.1 基本的なコードの作成

# my_python_app/main.py
import requests
from typing import Dict, Any

def fetch_data(url: str) -> Dict[str, Any]:
    """APIからデータを取得する"""
    response = requests.get(url)
    response.raise_for_status()
    return response.json()

def main():
    """メイン関数"""
    try:
        data = fetch_data("https://jsonplaceholder.typicode.com/posts/1")
        print(f"取得したデータ: {data}")
    except requests.RequestException as e:
        print(f"エラーが発生しました: {e}")

if __name__ == "__main__":
    main()

4.2 テストコードの作成

# tests/test_main.py
import pytest
from unittest.mock import Mock, patch
from my_python_app.main import fetch_data

def test_fetch_data_success():
    """fetch_dataの成功テスト"""
    mock_response = Mock()
    mock_response.json.return_value = {"id": 1, "title": "Test"}
    
    with patch("requests.get", return_value=mock_response):
        result = fetch_data("https://example.com")
        assert result == {"id": 1, "title": "Test"}

def test_fetch_data_error():
    """fetch_dataのエラーテスト"""
    with patch("requests.get", side_effect=Exception("Network error")):
        with pytest.raises(Exception):
            fetch_data("https://example.com")

📊 トラブルシューティング

よくある問題とその解決方法を紹介します。

1. 仮想環境が認識されない

# 仮想環境の場所を確認
poetry env info

# 手動でPython環境を指定
# VSCode/Cursorで .venv/bin/python を選択

2. importエラーが解決しない

// .vscode/settings.json に以下を追加
{
    "python.analysis.extraPaths": [
        "./src",
        "./my_python_app",
        "./tests"
    ],
    "python.analysis.autoImportCompletions": true
}

3. 型チェックエラーが発生する

// .vscode/settings.json に以下を追加
{
    "python.analysis.typeCheckingMode": "basic",
    "python.analysis.autoSearchPaths": true
}

4. パス解決の問題

# pyproject.toml に以下を追加
[tool.poetry]
packages = [
    { include = "my_python_app" }
]

# または、srcレイアウトを使用
[tool.poetry]
packages = [
    { include = "my_python_app", from = "src" }
]

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

# 仮想環境を削除して再作成
poetry env remove python
poetry install

# キャッシュをクリア
poetry cache clear . --all

✅ 完全な設定例

実際のプロジェクトで使える、完全な設定例を紹介します。

1. pyproject.toml

[tool.poetry]
name = "my-python-app"
version = "0.1.0"
description = "A Python application with Poetry"
authors = ["Your Name <your.email@example.com>"]
readme = "README.md"
packages = [{include = "my_python_app"}]

[tool.poetry.dependencies]
python = "^3.8"
requests = "^2.31.0"

[tool.poetry.group.dev.dependencies]
pytest = "^7.4.0"
black = "^24.3.0"
flake8 = "^6.0.0"
mypy = "^1.5.0"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

[tool.black]
line-length = 88
target-version = ['py38']

[tool.mypy]
python_version = "3.8"
warn_return_any = true
disallow_untyped_defs = true

2. poetry.toml

[virtualenvs]
in-project = true

3. .vscode/settings.json

{
    "python.defaultInterpreterPath": "./.venv/bin/python",
    "python.terminal.activateEnvironment": true,
    "python.analysis.extraPaths": [
        "./my_python_app",
        "./tests"
    ],
    "python.linting.enabled": true,
    "python.linting.flake8Enabled": true,
    "python.formatting.provider": "black",
    "python.testing.pytestEnabled": true,
    "python.testing.pytestArgs": [
        "tests"
    ],
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
        "source.organizeImports": true
    },
    "python.analysis.typeCheckingMode": "basic",
    "python.analysis.autoImportCompletions": true
}

4. .gitignore

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
build/
develop-eggs/
dist/
downloads/
eggs/
.eggs/
lib/
lib64/
parts/
sdist/
var/
wheels/
*.egg-info/
.installed.cfg
*.egg

# Virtual Environment
.venv/
venv/
ENV/

# IDE
.vscode/
.idea/
*.swp
*.swo

# Testing
.pytest_cache/
.coverage
htmlcov/

# MyPy
.mypy_cache/

🧭 おわりに

PoetryプロジェクトをVSCode/Cursorで正しく設定することで、開発効率が大幅に向上します。

設定のポイント

  1. プロジェクト内仮想環境: virtualenvs.in-project = true
  2. 正しいPython環境の選択: .venv/bin/python
  3. 適切なパス設定: python.analysis.extraPaths
  4. 開発ツールの統合: フォーマッター、リンター、テスト

推奨するワークフロー

  1. プロジェクト作成: poetry new
  2. 仮想環境設定: virtualenvs.in-project = true
  3. VSCode/Cursor設定: Python環境の選択
  4. 開発開始: エラーなしでコーディング

次のステップ

  1. 既存プロジェクトに設定を適用
  2. チームメンバーに設定方法を共有
  3. コード品質管理の導入 ← pre-commitを使った自動化はこちらを確認
  4. CI/CDパイプラインでの自動テスト
  5. コード品質ツールの導入

関連記事

https://zenn.dev/goshawk/articles/974679c38d7268
https://zenn.dev/goshawk/articles/67c95a59a1fe77

正しい設定を行うことで、PoetryとVSCode/Cursorが連携し、快適なPython開発環境を構築できます。ぜひ試してみてください！

Discussion