Visual Studio CodeでPython開発環境を構築する完全ガイド｜必須拡張機能と設定を解説

要約

VSCodeでPython開発環境を構築するには、公式Python拡張機能とPylance言語サーバーのインストールが必須である。Pythonインタープリタパスの設定、仮想環境の有効化、インポートパスの指定により、コード補完や型チェックが正常に動作する。さらに、デバッグ設定（launch.json）、テストフレームワーク統合（pytest、unittest）、Jupyter Notebook機能を活用することで、統合開発環境としての利便性が飛躍的に向上する。Black/autopep8によるコードフォーマット自動化、GitLens/GitHub Copilotなどの拡張機能追加により、プロフェッショナルなPython開発環境が完成する。

このガイドで得られるメリット

• 開発効率の大幅向上: インテリセンス、自動補完、型チェックにより、コーディング速度が向上する
• デバッグ作業の効率化: ブレークポイント、変数監視、ステップ実行により、バグ修正時間が短縮される
• コード品質の向上: 自動フォーマット、リンター、型チェックにより、一貫性のあるコードが維持される
• テスト自動化の実現: VSCode内でpytest/unittestを実行でき、TDD開発がスムーズになる
• Jupyter統合による分析効率化: データ分析・機械学習開発でノートブック環境がシームレスに利用できる
• 仮想環境管理の簡素化: プロジェクトごとの依存関係が明確に管理され、環境の切り替えが容易になる

この記事を読むのにかかる時間

約12分

検証環境

• OS: macOS Ventura v13.5.2（Windows/Linux でも同様の手順で設定可能）
• Python: 3.10.5
• VSCode: 1.85以降（最新版推奨）
• 必須拡張機能: Python (ms-python.python), Pylance (ms-python.vscode-pylance)

必須拡張機能のインストール

Python拡張機能

Microsoft公式のPython拡張機能は、VSCodeでPython開発を行う上で最も重要な拡張機能である。この拡張機能により、Pythonファイルの認識、インタープリタ選択、デバッグ機能、テスト実行機能が提供される。

インストール手順：

1. VSCodeを開く
2. サイドバーの拡張機能アイコンをクリック（またはCmd+Shift+X）
3. 検索欄に「Python」と入力
4. 「Python」（ms-python.python）を選択してインストール

Pylance言語サーバー

Pylanceは、Microsoft が開発した高性能なPython言語サーバーである。内部でPyrightという型チェッカーを使用しており、高速な型推論、自動補完、コードナビゲーション機能を提供する。

Pylanceの主な機能：

• 型チェック: 静的型解析による型エラーの検出
• インテリセンス: コンテキストに応じた高精度な自動補完
• 自動インポート: 未インポートのモジュールを自動的にインポート
• リファクタリング: シンボルの名前変更、インポートの整理
• 型ヒント: インライン型情報の表示

Pylanceは通常、Python拡張機能と一緒に自動インストールされるが、手動でインストールする場合は拡張機能検索で「Pylance」を検索する。

Pythonインタープリタの設定

インタープリタの選択

VSCodeでPythonコードを実行するには、使用するPythonインタープリタを指定する必要がある。

設定手順：

1. Cmd+Shift+P（Windows: Ctrl+Shift+P）でコマンドパレットを開く
2. 「Python: Select Interpreter」と入力
3. 使用したいPythonインタープリタを選択（システムPython、仮想環境など）

選択したインタープリタは、VSCodeのステータスバー右下に表示される。プロジェクトごとに異なる仮想環境を使用する場合、プロジェクトを開くたびに正しいインタープリタを選択する必要がある。

仮想環境の自動認識

VSCodeは、プロジェクトルート直下に以下の名前で仮想環境が存在する場合、自動的に認識する：

• .venv
• venv
• env

仮想環境の作成例：

copy# プロジェクトディレクトリで仮想環境を作成
python3 -m venv .venv

# 仮想環境の有効化（macOS/Linux）
source .venv/bin/activate

# 仮想環境の有効化（Windows）
.venv\Scripts\activate

# 依存パッケージのインストール
pip install -r requirements.txt

仮想環境を作成後、VSCodeでフォルダを開き直すと、自動的に仮想環境のインタープリタが選択される。

基本設定（settings.json）

VSCodeの設定は、プロジェクト単位（.vscode/settings.json）またはユーザー単位（グローバル設定）で管理できる。以下は、Python開発に推奨される基本設定である。

プロジェクト設定ファイルの作成

プロジェクトルートに .vscode/settings.json を作成する：

copy{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python",
  "python.languageServer": "Pylance",
  "python.analysis.typeCheckingMode": "basic",
  "python.analysis.autoImportCompletions": true,
  "python.analysis.diagnosticMode": "workspace",
  "python.analysis.extraPaths": [
    "${workspaceFolder}/src",
    "${workspaceFolder}/lib"
  ],
  "editor.formatOnSave": true,
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.codeActionsOnSave": {
      "source.organizeImports": "explicit"
    }
  },
  "python.testing.pytestEnabled": true,
  "python.testing.unittestEnabled": false,
  "python.testing.pytestArgs": [
    "tests"
  ]
}

設定項目の詳細解説

1. python.defaultInterpreterPath

使用するPythonインタープリタのパスを指定する。${workspaceFolder} はプロジェクトルートを表す変数である。

2. python.analysis.extraPaths

インポートパスを追加指定する。プロジェクト構成が以下のような場合：

copyproject/
├── src/
│   ├── module_a/
│   └── module_b/
└── lib/
    └── custom_lib/

src と lib を extraPaths に追加することで、これらのディレクトリ内のモジュールが正しく認識される。

copy# extraPaths設定により、以下のインポートが正しく解決される
from module_a import function_a
from custom_lib import helper

3. python.analysis.typeCheckingMode

型チェックの厳密度を設定する：

• off: 型チェックを無効化
• basic: 基本的な型チェック（推奨）
• strict: 厳格な型チェック（型ヒント必須）

4. editor.formatOnSave

ファイル保存時に自動的にコードをフォーマットする。Black、autopep8、yapfなどのフォーマッターと組み合わせて使用する。

デバッグ環境の構築

VSCodeの統合デバッガーは、Pythonアプリケーションのデバッグを強力にサポートする。ブレークポイント、ステップ実行、変数監視、コールスタック表示など、本格的なデバッグ機能が利用できる。

launch.jsonの作成

.vscode/launch.json を作成し、デバッグ設定を定義する：

copy{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Current File",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "justMyCode": true
    },
    {
      "name": "Python: Flask App",
      "type": "debugpy",
      "request": "launch",
      "module": "flask",
      "env": {
        "FLASK_APP": "app.py",
        "FLASK_DEBUG": "1"
      },
      "args": [
        "run",
        "--no-debugger",
        "--no-reload"
      ],
      "jinja": true,
      "justMyCode": true
    },
    {
      "name": "Python: Django",
      "type": "debugpy",
      "request": "launch",
      "program": "${workspaceFolder}/manage.py",
      "args": [
        "runserver",
        "8000"
      ],
      "django": true,
      "justMyCode": true
    },
    {
      "name": "Python: FastAPI",
      "type": "debugpy",
      "request": "launch",
      "module": "uvicorn",
      "args": [
        "main:app",
        "--reload"
      ],
      "jinja": true,
      "justMyCode": true
    }
  ]
}

デバッグ機能の使い方

ブレークポイントの設定：

1. コードの行番号左側をクリックすると赤い点が表示される
2. F5キーを押してデバッグを開始
3. ブレークポイントで実行が停止し、変数の値を確認できる

デバッグ操作：

• F5: 続行（次のブレークポイントまで実行）
• F10: ステップオーバー（次の行へ）
• F11: ステップイン（関数内部へ）
• Shift+F11: ステップアウト（関数から抜ける）
• Ctrl+Shift+F5: 再起動
• Shift+F5: 停止

変数の監視：

デバッグサイドバーの「VARIABLES」セクションで、現在のスコープ内の変数がすべて表示される。「WATCH」セクションに式を追加すれば、特定の変数や式の値を継続的に監視できる。

条件付きブレークポイント：

ブレークポイントを右クリックして「Edit Breakpoint」を選択すると、条件式やヒットカウントを設定できる。

copy# 例：i が 100 の場合のみ停止
for i in range(1000):
    process(i)  # ここに条件付きブレークポイント: i == 100

テスト実行環境の設定

VSCodeは、pytest と unittest の両方をネイティブサポートしている。テストエクスプローラーからテストの実行、デバッグ、結果確認が可能である。

pytest の設定

pytest のインストール：

copypip install pytest pytest-cov

settings.json での設定：

copy{
  "python.testing.pytestEnabled": true,
  "python.testing.pytestArgs": [
    "tests",
    "-v",
    "--cov=src",
    "--cov-report=html"
  ]
}

プロジェクト構成例：

copyproject/
├── src/
│   ├── __init__.py
│   └── calculator.py
├── tests/
│   ├── __init__.py
│   └── test_calculator.py
├── .vscode/
│   └── settings.json
└── pytest.ini

pytest.ini の設定：

copy[pytest]
testpaths = tests
python_files = test_*.py
python_classes = Test*
python_functions = test_*
addopts = -v --tb=short --strict-markers
markers =
    slow: marks tests as slow
    integration: marks tests as integration tests

テストの実行：

1. サイドバーのテストアイコンをクリック
2. 「Configure Python Tests」→「pytest」を選択
3. テストディレクトリ（tests）を指定
4. テストエクスプローラーに検出されたテストが表示される
5. 個別テスト、テストクラス、テストファイル単位で実行可能

unittest の設定

settings.json での設定：

copy{
  "python.testing.unittestEnabled": true,
  "python.testing.unittestArgs": [
    "-v",
    "-s",
    "tests",
    "-p",
    "test_*.py"
  ]
}

テストの記述例：

copyimport unittest
from src.calculator import add, subtract

class TestCalculator(unittest.TestCase):
    def test_add(self):
        self.assertEqual(add(2, 3), 5)
        self.assertEqual(add(-1, 1), 0)

    def test_subtract(self):
        self.assertEqual(subtract(5, 3), 2)
        self.assertEqual(subtract(0, 5), -5)

if __name__ == '__main__':
    unittest.main()

Jupyter Notebook の統合

VSCodeは、Jupyter Notebookをネイティブサポートしており、.ipynb ファイルを直接開いて編集・実行できる。データ分析や機械学習開発に非常に便利である。

Jupyter 拡張機能のインストール

Python拡張機能をインストールしていれば、Jupyter機能は自動的に利用可能になる。追加で以下をインストールすると、さらに便利になる：

copypip install jupyter notebook ipykernel

Notebookの作成と実行

新規Notebookの作成：

1. Cmd+Shift+P でコマンドパレットを開く
2. 「Jupyter: Create New Blank Notebook」を選択
3. カーネルを選択（プロジェクトの仮想環境を推奨）

セルの実行：

• Shift+Enter: セルを実行して次のセルに移動
• Ctrl+Enter: セルを実行（移動しない）
• Alt+Enter: セルを実行して下に新しいセルを追加

変数エクスプローラー：

Notebookの実行中、「Variables」ボタンをクリックすると、現在定義されているすべての変数が一覧表示される。DataFrameなどはクリックで内容を確認できる。

Pythonファイルでのセル実行：

通常の .py ファイルでも、# %% を使用してセルを定義できる：

copy# %%
import pandas as pd
import matplotlib.pyplot as plt

# %%
df = pd.read_csv('data.csv')
df.head()

# %%
plt.figure(figsize=(10, 6))
plt.plot(df['date'], df['value'])
plt.title('Time Series Data')
plt.show()

各セルの上に「Run Cell」というリンクが表示され、クリックすると対話的に実行できる。

コードフォーマッターの設定

コードフォーマッターを使用すると、PEP 8に準拠した一貫性のあるコードスタイルが自動的に維持される。

Black フォーマッターの設定

Blackは、Pythonコミュニティで広く採用されている「妥協のない」フォーマッターである。

インストール：

copypip install black

VSCode拡張機能のインストール：

拡張機能検索で「Black Formatter」（ms-python.black-formatter）をインストールする。

settings.json の設定：

copy{
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true
  },
  "black-formatter.args": [
    "--line-length",
    "100"
  ]
}

autopep8 フォーマッターの設定

autopep8は、PEP 8違反を自動修正するフォーマッターである。

インストール：

copypip install autopep8

settings.json の設定：

copy{
  "[python]": {
    "editor.defaultFormatter": "ms-python.autopep8",
    "editor.formatOnSave": true
  },
  "autopep8.args": [
    "--max-line-length",
    "100",
    "--aggressive",
    "--aggressive"
  ]
}

便利な拡張機能

GitLens

Gitの履歴、blame情報、コード作成者情報をインラインで表示する拡張機能。各行の最終更新者、コミットメッセージ、変更日時が確認できる。

GitHub Copilot

AIによるコード補完機能。関数名やコメントから、実装コードを自動生成する。有料サービスだが、学生や教育者は無料で利用できる。

Python Docstring Generator

関数定義から、docstringのテンプレートを自動生成する。Google、NumPy、Sphinxスタイルに対応している。

使い方：

1. 関数定義の直下で """ と入力
2. 自動的にdocstringテンプレートが生成される

copydef calculate_average(numbers: list[float]) -> float:
    """
    Calculate the average of a list of numbers.

    Args:
        numbers (list[float]): List of numbers to average

    Returns:
        float: The average value

    Raises:
        ValueError: If the list is empty
    """
    if not numbers:
        raise ValueError("Cannot calculate average of empty list")
    return sum(numbers) / len(numbers)

Python Indent

Pythonのインデント規則に従って、自動的に正しいインデントレベルを設定する。特に if、for、def などの後で効果を発揮する。

autoDocstring

関数のシグネチャから、docstringを自動生成する拡張機能。型ヒントがある場合、それを元にパラメータの型情報も生成される。

Better Comments

コメントを色分けして可読性を向上させる拡張機能。

copy# ! 重要な警告
# ? 質問や疑問点
# TODO: 後で実装
# * ハイライト

プロジェクト構成のベストプラクティス

標準的なプロジェクト構成

copyproject/
├── .vscode/
│   ├── settings.json
│   └── launch.json
├── src/
│   ├── __init__.py
│   ├── main.py
│   └── modules/
│       ├── __init__.py
│       └── helper.py
├── tests/
│   ├── __init__.py
│   └── test_helper.py
├── docs/
├── .venv/
├── .gitignore
├── requirements.txt
├── setup.py
├── pytest.ini
└── README.md

requirements.txt の管理

開発用依存関係を分離：

copy# requirements.txt（本番用）
flask==2.3.0
sqlalchemy==2.0.0
pydantic==2.0.0

# requirements-dev.txt（開発用）
-r requirements.txt
pytest==7.4.0
black==23.7.0
mypy==1.4.0
pylint==2.17.0

インストール：

copy# 本番用依存関係のみ
pip install -r requirements.txt

# 開発用依存関係も含む
pip install -r requirements-dev.txt

.gitignore の設定

copy# 仮想環境
.venv/
venv/
env/

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python

# テスト・カバレッジ
.pytest_cache/
.coverage
htmlcov/
*.cover

# IDE
.vscode/
.idea/

# 環境変数
.env
.env.local

トラブルシューティング

1. インポートエラーが解決されない

症状：

copyfrom src.modules import helper  # インポートエラー

モジュールが存在するのに、VSCodeが認識せず、波線が表示される。

解決策：

.vscode/settings.json に extraPaths を追加：

copy{
  "python.analysis.extraPaths": [
    "${workspaceFolder}/src"
  ]
}

または、PYTHONPATH 環境変数を設定：

copy{
  "terminal.integrated.env.osx": {
    "PYTHONPATH": "${workspaceFolder}/src:${env:PYTHONPATH}"
  },
  "terminal.integrated.env.linux": {
    "PYTHONPATH": "${workspaceFolder}/src:${env:PYTHONPATH}"
  },
  "terminal.integrated.env.windows": {
    "PYTHONPATH": "${workspaceFolder}/src;${env:PYTHONPATH}"
  }
}

プロジェクトルートに init.py を追加：

srcディレクトリをPythonパッケージとして認識させるため、src/__init__.py を作成する。

2. 仮想環境のインタープリタが認識されない

症状：

仮想環境を作成したのに、VSCodeが認識せず、システムPythonが選択されている。

解決策：

フォルダを開き直す：

copy# 一度VSCodeを閉じて、プロジェクトフォルダを開き直す
code .

手動でインタープリタを選択：

1. Cmd+Shift+P
2. 「Python: Select Interpreter」
3. .venv/bin/python を選択

settings.json でパスを明示的に指定：

copy{
  "python.defaultInterpreterPath": "${workspaceFolder}/.venv/bin/python"
}

3. デバッガーが起動しない

症状：

F5キーを押しても、「Cannot find module 'debugpy'」というエラーが表示される。

解決策：

debugpy をインストール：

copypip install debugpy

正しいPythonインタープリタを選択：

デバッガーは、VSCodeで選択されているインタープリタを使用する。ステータスバーで正しいインタープリタが選択されているか確認する。

launch.json を確認：

copy{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "Python: Current File",
      "type": "debugpy",  // "python" ではなく "debugpy"
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal"
    }
  ]
}

4. テストが検出されない

症状：

テストファイルが存在するのに、テストエクスプローラーに表示されない。

解決策：

テスト設定を再構成：

1. Cmd+Shift+P
2. 「Python: Configure Tests」
3. pytest または unittest を選択
4. テストディレクトリを指定

テスト検出をリフレッシュ：

テストエクスプローラーの更新ボタン（円形矢印）をクリックする。

ファイル名規則を確認：

pytest: test_*.py または *_test.py unittest: test*.py

init.py を追加：

testsディレクトリに __init__.py を作成する。

5. フォーマッターが動作しない

症状：

ファイル保存時にコードがフォーマットされない。

解決策：

フォーマッター拡張機能がインストールされているか確認：

• Black Formatter (ms-python.black-formatter)
• autopep8 (ms-python.autopep8)

settings.json を確認：

copy{
  "editor.formatOnSave": true,
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter"
  }
}

フォーマッターがインストールされているか確認：

copypip install black
# または
pip install autopep8

FAQ

Q1: VSCodeとPyCharmの違いは？どちらを選ぶべき？

A: VSCodeは軽量で起動が速く、拡張機能で多言語対応が可能である。PyCharmはPython専用のフル機能IDEで、リファクタリング機能やデータベース統合が強力である。個人開発やマルチ言語プロジェクトではVSCode、大規模Pythonプロジェクトや高度なリファクタリングが必要な場合はPyCharmが適している。

Q2: 仮想環境は必須？システムPythonでは駄目？

A: 仮想環境の使用を強く推奨する。プロジェクトごとに依存関係を分離することで、パッケージバージョンの競合を防ぎ、環境の再現性が向上する。venv または virtualenv で簡単に作成できる。

Q3: PylanceとPyrightの違いは？

A: Pyrightは型チェッカーのコアエンジンであり、CLIツールとして単体で使用できる。Pylanceは、PyrightをベースにしたVSCode専用の言語サーバーであり、エディタ統合機能（インテリセンス、ナビゲーション）が追加されている。VSCodeではPylanceを使用し、CI/CDではPyrightを使用するのが一般的である。

Q4: Black と autopep8 の違いは？どちらを選ぶべき？

A: Blackは「妥協のない」フォーマッターで、設定オプションが少なく、チーム全体で一貫したスタイルを強制する。autopep8はPEP 8準拠のフォーマッターで、カスタマイズ性が高い。チーム開発ではBlack、個人の好みを反映したい場合はautopep8が適している。

Q5: テストはpytestとunittest、どちらを使うべき？

A: pytestを推奨する。pytestはシンプルな記法、豊富なプラグイン、強力なフィクスチャ機能を持つ。unittestは標準ライブラリであり、追加インストール不要だが、やや冗長な記法となる。新規プロジェクトではpytestが主流である。

Q6: Jupyter NotebookとPythonファイル、どう使い分ける？

A: データ探索、可視化、実験的コードではJupyter Notebookが適している。本番コード、ライブラリ、テストコードでは通常のPythonファイルが適している。Notebookで実験後、確定したコードを .py ファイルに移行するワークフローが効率的である。

Q7: GitLensは無料で使える？

A: GitLensの基本機能は無料で使用できる。一部の高度な機能（Visual File History、Worktrees）は有料のGitLens+ サブスクリプションが必要である。個人開発では無料版で十分な機能が提供される。

Q8: GitHub Copilotは学生は無料？

A: GitHub Copilotは、学生、教育者、人気オープンソースプロジェクトのメンテナーに無料で提供される。GitHub Education（Student Developer Pack）に登録することで利用できる。一般ユーザーは月額$10または年額$100である。

Q9: リモート開発（SSH、Container）は可能？

A: VSCodeの「Remote - SSH」拡張機能を使用すれば、リモートサーバー上のPython環境で開発できる。「Dev Containers」拡張機能を使用すれば、Dockerコンテナ内で開発できる。どちらもローカル開発と同じ体験が得られる。

Q10: 複数のPythonバージョンを管理するには？

A: pyenv（macOS/Linux）またはpyenv-win（Windows）を使用する。複数のPythonバージョンをインストールし、プロジェクトごとに切り替えられる。VSCodeは、pyenvでインストールされたPythonを自動検出する。

copy# pyenvのインストール（macOS）
brew install pyenv

# Python 3.11をインストール
pyenv install 3.11.0

# プロジェクトでPython 3.11を使用
pyenv local 3.11.0

まとめ

Visual Studio CodeをPython開発環境として構築するには、Python拡張機能とPylanceのインストールが出発点である。Pythonインタープリタの正しい設定、仮想環境の活用、インポートパスの指定により、コード補完や型チェックが適切に機能する。

さらに、デバッグ設定（launch.json）により、ブレークポイントやステップ実行を使った効率的なデバッグが可能になる。pytest/unittestの統合により、VSCode内でテストの実行とデバッグができる。Jupyter Notebookのネイティブサポートにより、データ分析や機械学習開発がシームレスに行える。

Black/autopep8によるコードフォーマット自動化、GitLens/GitHub Copilotなどの拡張機能追加により、プロフェッショナルなPython開発環境が完成する。適切な設定により、VSCodeはPyCharmに匹敵する強力なPython IDEとなり、開発効率が飛躍的に向上する。