VSCode Python 開発環境セットアップ

1. VSCode のインストール

VSCode（Visual Studio Code）はMicrosoftが開発した無料のコードエディターです。軽量で高機能、豊富な拡張機能により世界中の開発者に愛用されています。

1. 1
   公式サイトからダウンロード

   https://code.visualstudio.com/ にアクセスし、お使いのOSに合ったインストーラーをダウンロードします。

2. 2
   インストールオプション（Windows）

   Windowsの場合、インストール時に以下のオプションにチェックを入れると便利です：

   • 「エクスプローラーのファイルコンテキストメニューに[Codeで開く]アクションを追加する」
   • 「エクスプローラーのディレクトリコンテキストメニューに[Codeで開く]アクションを追加する」
   • 「PATHへの追加」
3. 3
   起動確認

   インストール完了後、VSCodeを起動します。日本語UIにするには次のセクションの拡張機能をインストールします。

2. Python 必須拡張機能

VSCodeの左側の拡張機能アイコン（四角が4つのアイコン）をクリックし、検索ボックスに名前を入力してインストールします。

必須拡張機能

推奨拡張機能

3. Python インタープリターの設定

VSCodeに使用するPythonのバージョンを教える設定です。仮想環境を使っている場合は仮想環境のインタープリターを選択します。

1. 1
   コマンドパレットを開く

   Ctrl + Shift + P（Mac: Cmd + Shift + P）でコマンドパレットを開きます。

2. 2
   「Python: インタープリターを選択」を実行

   コマンドパレットに「Python: Select Interpreter」または「Python: インタープリターを選択」と入力して選択します。

3. 3
   使用するPythonを選択

   表示されるリストから使用したいPythonを選択します。仮想環境（venv）を使っている場合は ./venv/bin/python または ./venv/Scripts/python.exe を選択してください。

4. コードの実行方法

方法1: 再生ボタンで実行

右上の ▶ ボタン（実行ボタン）をクリックするか、Shift + F5 でファイルを実行します。

方法2: ターミナルで実行

Ctrl + `（バッククォート）でターミナルを開き、python ファイル名.py を実行します。

python hello.py

方法3: インタラクティブウィンドウ

コードを選択して右クリック → 「選択範囲をPython インタラクティブで実行」を選ぶと、Jupyter のようなインタラクティブウィンドウで実行できます。

5. デバッグの使い方

デバッグを使うとプログラムを途中で止めて変数の値を確認できます。バグ修正に非常に役立ちます。

ブレークポイントの設定

1. 1
   ブレークポイントを設定

   止めたい行番号の左側をクリックすると赤い丸●が表示されます（ブレークポイント）。

2. 2
   デバッグモードで実行

   F5 を押すか「実行とデバッグ」パネルから「Python ファイル」を選んで実行します。

3. 3
   変数を確認

   ブレークポイントで停止したら、左のパネルで変数の値を確認できます。F10（次の行へ）、F11（関数の中に入る）で一行ずつ実行できます。

デバッグのショートカット

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

コードフォーマッターを使うと、保存するだけでコードのインデントやスペースを自動的に整えてくれます。チーム開発でコードスタイルを統一するのにも役立ちます。

Black のインストールと設定

# Blackをインストール
pip install black

VSCodeの設定（Ctrl+,）で以下を設定するか、settings.json に追加します：

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

これで Ctrl+S で保存するたびにコードが自動整形されます。

7. おすすめ settings.json 設定

Ctrl+Shift+P → 「基本設定: ユーザー設定を開く (JSON)」で設定ファイルを開きます。

{
  // エディター基本設定
  "editor.fontSize": 14,
  "editor.tabSize": 4,
  "editor.insertSpaces": true,
  "editor.wordWrap": "on",
  "editor.minimap.enabled": false,
  "editor.rulers": [79, 119],
  "editor.renderWhitespace": "boundary",

  // Python設定
  "python.languageServer": "Pylance",
  "python.analysis.typeCheckingMode": "basic",
  "python.analysis.autoImportCompletions": true,

  // フォーマッター設定
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.organizeImports": "explicit"
    }
  },

  // ターミナル設定
  "terminal.integrated.fontSize": 13,

  // ファイル設定
  "files.autoSave": "afterDelay",
  "files.autoSaveDelay": 1000,
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true,

  // テーマ（お好みで）
  "workbench.colorTheme": "Default Dark Modern",
  "workbench.iconTheme": "material-icon-theme"
}

8. 覚えておきたいショートカット

9. 効率的な開発ワークフロー

VSCode はカスタマイズ自由度が高いため、人によって生産性が大きく変わります。ここでは Python 開発を始めたばかりの方向けに、最初に押さえておくと差がつく実践テクニックを紹介します。

9.1 仮想環境を VSCode に認識させる

プロジェクトごとに venv 仮想環境を作っている場合、VSCode の Python インタープリター選択を「プロジェクト内 venv」に切り替えることで、デバッガ・補完・インストール済パッケージ表示が全て連動します。

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

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

# 仮想環境内でパッケージインストール
pip install requests pandas

その後 VSCode で Ctrl+Shift+P（Mac: Cmd+Shift+P） → 「Python: Select Interpreter」を実行し、.venv\Scripts\python.exe（または .venv/bin/python）を選択すれば連動完了です。ワークスペース設定として .vscode/settings.json に保存されるため、次回からは自動でこの環境が選ばれます。

9.2 launch.json でデバッグ設定を保存する

デバッグ実行のたびに F5 で都度設定するのではなく、.vscode/launch.json に保存しておけば、同じプロジェクトで複数の実行構成（例：本番用 / テスト用 / 引数違い）をワンクリックで切り替えられます。

// .vscode/launch.json
{
  "version": "0.2.0",
  "configurations": [
    {
      "name": "現在のファイルを実行",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "justMyCode": true
    },
    {
      "name": "main.py を引数つきで実行",
      "type": "debugpy",
      "request": "launch",
      "program": "${workspaceFolder}/main.py",
      "args": ["--input", "data.csv", "--verbose"],
      "console": "integratedTerminal"
    }
  ]
}

9.3 .gitignore は最初に作る

Python プロジェクトでは、コミットしてはいけないファイルが決まっています。仮想環境フォルダ・キャッシュ・秘密情報を Git 管理から外すために、プロジェクト作成時に .gitignore を作っておく習慣が重要です。

# .gitignore（Python プロジェクト推奨テンプレート）
__pycache__/
*.py[cod]
*.egg-info/

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

# IDE
.vscode/settings.json   # ローカル設定は共有しない場合
.idea/

# 環境変数・秘密情報
.env
.env.local
*.key
secrets/

# OS が自動生成するファイル
.DS_Store
Thumbs.db

9.4 ターミナル統合と pip コマンドを使い分ける

VSCode の統合ターミナル（Ctrl+`）は、開いているプロジェクトの仮想環境を自動でアクティベートします。OS のコマンドプロンプトでなく VSCode 内のターミナルから pip install することで、誤ってシステム全体に余計なパッケージを入れる事故を防げます。

10. よくあるトラブルと対処

VSCode で Python 開発を始めたばかりの方が遭遇しがちな問題と、その解決法をまとめます。エラーメッセージそのままで検索する前に、まずここをチェックしてみてください。

10.1 「Pylance が import を解決できない」と表示される

症状：自作モジュールや pip でインストールしたパッケージに対して、赤い波線で「unresolved import」と表示される。実行はできるのに補完が効かない状態です。

原因：VSCode が現在のワークスペースの Python インタープリターを正しく認識できていません。pip install したのにシステム Python が選ばれている、または仮想環境が切り替わっていないケースが多いです。

対処：Ctrl+Shift+P → 「Python: Select Interpreter」で正しいインタープリター（プロジェクト内の .venv 等）を選び直します。それでも解決しない場合は VSCode を一度リロード（Ctrl+Shift+P → 「Developer: Reload Window」）してください。

10.2 デバッグの F5 で「Python ファイルとして実行できない」

症状：F5 を押すと選択画面が出るが、Python 用の選択肢が現れない、または実行が始まらない。

対処：拡張機能タブで Python（Microsoft 公式） がインストール・有効化されているか確認します。インストール直後は VSCode の再起動が必要な場合があります。それでも動かない場合は、.vscode/launch.json を §9.2 のテンプレートから手動で作成すると確実です。

10.3 「Linter / Formatter が動かない」

症状：保存時に Black や Ruff のフォーマットが実行されない。

対処：(1) 該当 Formatter が pip でインストール済か（pip install black または pip install ruff）、(2) settings.json に "editor.formatOnSave": true と該当言語の "editor.defaultFormatter" が指定されているか、(3) ファイル末尾に表示される言語モードが「Python」になっているかを確認します。

10.4 「日本語入力が変・カーソル位置がずれる」

症状：日本語入力中に変換候補ウィンドウが変な位置に出る、確定後にカーソル位置がずれる。

対処：VSCode の 「Editor: Inline Suggest Enabled」 設定や GitHub Copilot の補完がインライン候補を出すことで IME と衝突するケースがあります。設定で「IME」検索し、関連オプションを切り替えて様子を見ましょう。改善しない場合は VSCode を最新版にアップデートすると解決することが多いです。

10.5 「ターミナルで pip install したのに使えない」

症状：VSCode のターミナルで pip install requests したのに、コード上では import エラー。

対処：ターミナルがアクティベートしている Python と、コード実行時の Python が一致していない典型例です。ターミナルで python -c "import sys; print(sys.executable)" を実行して使われている Python のパスを確認し、Ctrl+Shift+P → 「Python: Select Interpreter」で同じものを選ぶことで解決します。