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

1. VSCode のインストール

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

まだPython本体を入れていない場合は、先にPythonのインストール手順を済ませてから本ページに戻ってください。

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

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

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

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

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

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

macOS は配布されたアプリケーションをアプリケーションフォルダーへドラッグするだけ、Linux は各ディストリビューション向けのパッケージが用意されています。どのOSでも、フォルダーを開いた状態で作業するのが基本です。1つのファイルではなく「プロジェクトのフォルダー」を開くと、この記事で扱う設定ファイル（.vscode/settings.json・.vscode/launch.json）がそのフォルダーの中に作られ、プロジェクトごとに設定を持てるようになります。

2. Python 必須拡張機能

VSCodeの左側の拡張機能アイコン（四角が4つのアイコン）をクリックし、検索ボックスに名前を入力してインストールします。同じ名前の拡張が複数並ぶことがあるので、検索ボックスに拡張機能ID（例: ms-python.python）をそのまま貼り付けて選ぶと、publisher を間違えずに済みます。

最初に入れるのは Microsoft 公式の Python 拡張ひとつだけで構いません。この拡張は Pylance（補完・型チェック）、Python Debugger（デバッグ）、Python Environments（環境の管理）を付随的に一緒にインストールする作りになっているため、1つ入れるだけで補完とデバッグが同時に立ち上がります。整形（フォーマッター）とリンターは Python 拡張に含まれておらず、後述するとおり別の拡張として選んで入れます。

必須拡張機能

推奨拡張機能

拡張機能を入れる順番と役割の早見表

初回は上から順に入れ、下の3つは必要になってから足すのがおすすめです。無料で完結する構成なので、この記事の手順に課金は発生しません。

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\Scripts\python.exe（Windows）または .venv/bin/python（macOS / Linux）を選択してください。作り方とVSCodeとの連携は§4で詳しく扱います。

ここで選んだインタープリターはそのフォルダー（ワークスペース）単位で記憶されます。つまりプロジェクトごとに別のPythonを割り当てられるということで、次に同じフォルダーを開いたときは選び直す必要はありません。記憶される場所はVSCodeや拡張機能のバージョンによって異なり、.vscode/settings.json に書き出される場合もあれば、VSCode内部にだけ保存されて設定ファイルが作られない場合もあります。

選択がなぜ重要かというと、VSCodeはこの1つの設定を 補完（Pylance）・デバッグ実行・統合ターミナルの3か所すべての土台にしているからです。ここがずれていると「実行はできるのに補完が効かない」「pip install したのに import できない」といった、原因が見えにくい不具合がまとめて発生します。次の章で、その土台をプロジェクト単位に切り分ける仮想環境（venv）との連携を扱います。

4. 仮想環境（venv）と VSCode の連携

仮想環境（venv）は、プロジェクトごとにライブラリの置き場所を分ける仕組みです。分けておくと、あるプロジェクトのために入れたライブラリが別のプロジェクトを壊すことがなくなります。Python本体側の作り方はPythonのインストール手順の仮想環境（venv）の章で解説しているので、ここではVSCodeとつなぐところだけを扱います。

ここを飛ばすと、初心者がいちばん時間を溶かす「pip install したはずなのに ModuleNotFoundError」に必ず出会います。逆に、この章の3ステップを最初に済ませておけば、そのエラーの大半は起きません。

4.1 プロジェクト直下に .venv を作る

プロジェクトのフォルダーをVSCodeで開き、Ctrl+` でターミナルを出して次を実行します。フォルダー名は .venv にしておくのが実用的です。VSCodeはワークスペース内の .venv を自動的に探しに行くため、名前を合わせるだけで検出されやすくなります。

# Windows（PowerShell）
python -m venv .venv

# macOS / Linux
python3 -m venv .venv

実行するとフォルダー内に .venv ができます。中身は Windows なら .venv\Scripts\python.exe、macOS / Linux なら .venv/bin/python というそのプロジェクト専用のPythonです。

4.2 VSCode に .venv を認識させる

Ctrl+Shift+P →「Python: Select Interpreter（インタープリターを選択）」で、一覧から .venv が付いたものを選びます。('.venv': venv) のような表示が目印です。一覧に出てこない場合は「インタープリターパスを入力」から .venv\Scripts\python.exe を直接指定できます。

選択後、ステータスバーの表示が .venv に変われば連携完了です。この時点で、補完・デバッグ・ターミナルの3つが同じPythonを向きます。

4.3 統合ターミナルは自動でアクティベートされる

VSCodeの統合ターミナルは、選択中の環境を自動でアクティベートしてから開きます。プロンプトの先頭に (.venv) と出ていればアクティベート済みで、その状態の pip install はプロジェクト内だけに入ります。

すでに開いているターミナルには反映されないので、インタープリターを切り替えたらターミナルを一度閉じて開き直すのが確実です（ターミナルパネルのゴミ箱アイコンで破棄 → Ctrl+` で新規）。

4.4 「VSCodeでだけ ModuleNotFoundError」が出るときの切り分け

コマンドプロンプトでは動くのにVSCodeでだけ落ちる、あるいはその逆。原因は、筆者が見てきた範囲ではほぼ例外なく「入れたPythonと実行しているPythonが違う」ことです。犯人探しは、両方で次の1行を実行してパスが一致するかを見るのが最短です。

python -c "import sys; print(sys.executable)"

ターミナルで表示されたパスと、ステータスバーに出ているインタープリターが同じなら環境は揃っています。違っていたら次の表で自分の状況を確認してください。

迷ったときの原則はひとつ、pip ではなく python -m pip で入れることです。この書き方なら「いま選ばれているPython」に確実に入るため、取り違えが構造的に起きません。エラーメッセージ側から原因をたどりたい場合はModuleNotFoundErrorの解説もあわせて確認してください。

5. コードの実行方法

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

右上の ▶ ボタン（実行ボタン）は「デバッグなしで実行」に相当します。クリックするか Ctrl+F5 でファイルを実行します。ブレークポイントを使ってデバッグ付きで実行したいときは F5 です。

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

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

python hello.py

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

コードを選択して右クリック → 「選択範囲をPython インタラクティブで実行」を選ぶと、Jupyterのようなインタラクティブウィンドウで実行できます。このメニューは Jupyter 拡張機能（ms-toolsai.jupyter）が入っている場合に使えます。pandas の結果を少しずつ確かめたいときなど、ファイル全体を毎回動かしたくない場面で便利です。

3つの実行方法の使い分け

6. デバッグの使い方

デバッグを使うとプログラムを途中で止めて変数の値を確認できます。バグ修正に非常に役立ちます。print() を挿しては消す作業を繰り返している人ほど、ここで時間が返ってきます。変数の中身を1行ずつ目で追えるようになるので、「なぜかループが1回多い」「なぜか空のリストが返る」といった原因が、推測ではなく観察で分かります。

ブレークポイントの設定

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

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

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

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

3. 3
   変数を確認

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

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

止まったあとに見る4つのパネル

ブレークポイントで停止すると、左側に4つの領域が並びます。役割を知っておくと、止めたあとに何を見ればいいか迷いません。

停止中は下部のデバッグコンソールでその場の変数を使った式を評価できます。data[3]["price"] のように打てば結果がすぐ返るので、条件式が思ったとおりか、その場で試せます。

条件付きブレークポイントとログポイント

1万件のループの中で「i が 500 のときだけ」止めたい、という場面があります。行番号の左を右クリックして「条件付きブレークポイントの追加」を選び、i == 500 のような式を入れると、その条件が真のときだけ停止します。

同じメニューにあるログポイントは、止めずにメッセージだけ出す仕組みです。メッセージ欄に 現在の値: {price} のように書くと、波括弧の中が実際の値に置き換わってデバッグコンソールに出ます。print() を書き足してあとで消す作業が丸ごと不要になり、消し忘れがコードに残る事故も防げます。

7. launch.json はどこにある？ 作り方と設定例

launch.json は「どのファイルを、どんな引数と環境変数で、どう起動してデバッグするか」を保存しておくファイルです。F5 のたびに選択肢を選び直している人は、これを作ればワンクリックで同じ実行を再現できます。

7.1 場所はプロジェクト直下の .vscode フォルダー

結論から言うと、launch.json の置き場所はVSCodeで開いているフォルダーの直下にある .vscode フォルダーの中です。パスで書くと プロジェクト/.vscode/launch.json になります。ユーザー設定のようにOSのどこか深い場所にあるのではなく、プロジェクトごとに1つという点がポイントです。

.vscode はドットで始まるため、OSのファイル一覧では隠しフォルダー扱いになることがあります。VSCodeのエクスプローラー（左側のファイル一覧）ではそのまま表示されるので、見つからないときはVSCode側で探すのが早いです。表示されていない場合は、単にまだ作られていないだけです。

7.2 作り方は「実行とデバッグ」から2クリック

1. 1
   「実行とデバッグ」パネルを開く

   左のアクティビティバーで再生ボタンに虫が付いたアイコン、または Ctrl+Shift+D（Mac: Cmd+Shift+D）。

2. 2
   「launch.json ファイルを作成します」をクリック

   デバッガーの選択肢が出るので Python Debugger →「Python ファイル」を選びます。これで .vscode/launch.json が自動生成されます。

3. 3
   あとから開くとき

   エクスプローラーから直接開くか、コマンドパレット（Ctrl+Shift+P）で「デバッグ: launch.json を開く」を実行します。手で .vscode フォルダーを作り、その中に launch.json を置いても同じです。

7.3 Python向けの設定例（引数・作業フォルダー付き）

自動生成された直後は「現在のファイルを実行」だけのシンプルな内容です。configurations の配列に要素を足すと、実行とデバッグパネルのドロップダウンに構成が並び、選んで F5 で切り替えられます。

{
  "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"],
      "cwd": "${workspaceFolder}",
      "console": "integratedTerminal"
    },
    {
      "name": "ライブラリの中まで追いかける",
      "type": "debugpy",
      "request": "launch",
      "program": "${file}",
      "console": "integratedTerminal",
      "justMyCode": false
    }
  ]
}

launch.json はコメント（//）を書ける形式ですが、末尾のカンマは書けません。構成を1つ消したときにカンマが余って赤波線が出るのは、ほぼこれが原因です。

7.4 環境変数を渡す（env / envFile）

APIキーやデータベースの接続先など、コードに直接書きたくない値は環境変数で渡します。VSCodeのデバッグ実行では方法が2つあります。

1つ目は env に直接書く方法です。切り替えの少ない値や、秘密ではない設定に向いています。

{
  "name": "開発モードで実行",
  "type": "debugpy",
  "request": "launch",
  "program": "${workspaceFolder}/main.py",
  "console": "integratedTerminal",
  "env": {
    "APP_ENV": "development",
    "LOG_LEVEL": "DEBUG"
  }
}

2つ目は envFile でファイルから読み込む方法です。APIキーのような秘密の値はこちらを使ってください。ファイルを .gitignore に入れておけば、うっかりGitHubへ公開する事故を防げます。

API_KEY=xxxxxxxxxxxxxxxx
DB_URL=postgresql://localhost:5432/sample

{
  "name": ".env を読み込んで実行",
  "type": "debugpy",
  "request": "launch",
  "program": "${workspaceFolder}/main.py",
  "console": "integratedTerminal",
  "envFile": "${workspaceFolder}/.env"
}

Python側は os.environ で受け取ります。値が無いときに落とさず既定値を使いたい場合は os.environ.get() が便利です。

import os

api_key = os.environ.get("API_KEY", "")
app_env = os.environ.get("APP_ENV", "production")

if not api_key:
    raise SystemExit("API_KEY が設定されていません。.env を確認してください")

print(f"{app_env} モードで起動します")

なお、環境変数定義ファイルの既定値はVSCodeの設定 python.envFile にあり、VS Code公式ドキュメント（Python environments）では "${workspaceFolder}/.env" とされています。プロジェクト直下に .env を置いておけば、launch.json に書かなくても読まれるのが基本の挙動です。統合ターミナルにも同じ変数を流したい場合は、別の設定が必要になることがあるため、ターミナルから python main.py したときに値が空なら、まずデバッグ実行（F5）で確かめてください。

8. コードフォーマッターの設定（Black・Ruff）

コードフォーマッターは、インデントの深さ・カンマの後ろのスペース・改行位置といった「見た目のルール」を自動で揃えるツールです。Ctrl+S のたびに整形されるよう設定しておくと、書き方の細部を考える時間がまるごと消えます。学習中は「動くこと」に集中でき、あとから自分のコードを読み返したときも読みやすい。この章はそのための設定を、迷いようがない順番で並べます。

8.1 フォーマッターとリンターは役割が違う

混同されがちですが、両者は目的が別です。片方だけでも成立しますが、役割を知っておくと拡張機能を選ぶときに迷いません。

まず入れるべきはフォーマッターです。リンターは、書けるコードが増えて「未使用の変数」「使っていない import」が気になり始めてからで間に合います。

8.2 保存時に自動整形させる設定（3ステップ）

保存時整形が動かない原因は、ほぼこの3つのどれかが欠けていることです。逆に言えば、3つ揃えれば動きます。

1. 1
   フォーマッターの拡張機能を入れる

   Black Formatter（ms-python.black-formatter）か Ruff（charliermarsh.ruff）のどちらか。Python拡張には整形機能が含まれていないため、この拡張を入れないと何も起きません。

2. 2
   Python用の既定フォーマッターを指定する

   settings.json の "[python]" の中で editor.defaultFormatter を指定します。ここを飛ばすと、整形時に「どのフォーマッターを使うか」を毎回聞かれて止まります。

3. 3
   保存時整形を有効にする

   "editor.formatOnSave": true。全言語に効かせたくない場合は、手順2と同じ "[python]" の中に入れれば Python ファイルだけに限定できます。

Black を使う場合の最小構成は次のとおりです。Ctrl+Shift+P →「基本設定: ユーザー設定を開く (JSON)」で開いたファイルに追記します。

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

Ruff を使う場合は、指定先を差し替えるだけです。

{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true
  }
}

設定したら、わざとスペースを乱した行を作って Ctrl+S してください。整った瞬間が動作確認です。何も起きない場合は8.7の確認順へ進んでください。

8.3 Black — 選択肢が少ないことが価値

Black は「スタイルで議論させない」ことを狙ったフォーマッターです。Black 公式ドキュメント（The Black code style）はスタイルの設定項目を意図的に絞っていると明言しており、既定の1行の長さは 88文字、文字列は原則ダブルクォートに統一されます。要素の末尾に自分でカンマを付けると1行に収まる場合でも複数行に展開される（マジックトレーリングカンマ）といった決まりもあります。

うれしいのは、誰が書いても同じ形に落ちるので、スタイルを迷う時間がなくなることです。学習中でも「この改行位置で合っているのか」と悩む回数が減ります。

拡張機能はBlack本体を同梱しており（2026年8月時点の拡張機能ページの表記では black=26.1.0）、pip install black をしなくても保存時整形は動きます。プロジェクトやCIとバージョンを揃えたいときだけ、仮想環境に入れたBlackを使わせる設定に変更します。

{
  "black-formatter.args": ["--line-length", "100"],
  "black-formatter.importStrategy": "fromEnvironment"
}

importStrategy の既定は useBundled（拡張に同梱されたBlackを使う）で、fromEnvironment にすると選択中の環境にインストールされたBlackを優先します。「人によって整形結果が違う」を避けたいときは、pip install black したうえで fromEnvironment に切り替えるのが確実です。

8.4 Ruff — 整形とチェックを1つにまとめる

Ruff は Rust で書かれた高速なツールで、リンターとフォーマッターを兼ねます。フォーマッターは Black の代替として設計されており、Ruff 公式ドキュメント（Formatter）は「既存の Black 整形済みコードに対してほぼ同一の出力を出すことを意図している」と述べ、多数のBlack整形済みプロジェクトでの検証で99.9%を超える行が同一に整形されたと説明しています。ただし f-string の波括弧内を整形するなど、意図的な差異も公式に明記されています。完全一致が保証されるわけではない点は押さえておいてください（2026年8月時点の公式ドキュメント）。

VSCode拡張はRuff本体を同梱しており（2026年8月時点の拡張機能ページの表記で ruff==0.16.2。同梱バージョンは拡張の更新で変わります）、こちらも pip install ruff なしで動きます。整形に加えて、保存時の自動修正やimport並べ替えまでやらせるなら次の設定です。

{
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
      "source.fixAll.ruff": "explicit",
      "source.organizeImports.ruff": "explicit"
    }
  }
}

source.fixAll.ruff は自動修正できる指摘（未使用importの削除など）を保存時に適用し、source.organizeImports.ruff は import を並べ替えます。"explicit" は「明示的に保存したときに実行する」という指定です。

8.5 Black と Ruff、どちらを選ぶか

どちらも無料で、保存時整形という目的だけ見れば体感差はほとんどありません。判断材料は「自分の状況」です。

迷ったら、最初のうちは Black をおすすめします。書籍や記事の前提になっていることが多く、困ったときに検索で答えが見つかりやすいからです。自分のコードが増えて「未使用importの掃除まで自動でやりたい」と感じたら Ruff に一本化する、という順番が自然です。

逆に、BlackとRuffの両方を整形役として同時に有効にするのは避けてください。どちらが最後に走ったかで結果が変わり、Gitの差分が無意味に増えます。整形役はどちらか一方に決める、が鉄則です。

8.6 import の並べ替え（isort との関係）

整形とは別に、import 文を標準ライブラリ・サードパーティ・自作の順に並べ替える機能があります。Black は整形しかしないため、Blackを使う構成では isort 拡張（ms-python.isort）を追加し、保存時のコードアクションで呼び出します。

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

一方 Ruff では、ruff format 自体は import を並べ替えません。Ruff 公式ドキュメント（Sorting imports）もリンター側の I ルール（ruff check --select I --fix）と組み合わせる運用を案内しています。VSCode上では前述の source.organizeImports.ruff がその役目です。

整形とimport整理は別物、と覚えておくと「保存しても import の順番が直らない」という混乱を避けられます。

8.7 フォーマッターが効かないときの確認順

保存しても何も起きないときは、次の順に見ると原因が1つに絞れます。上ほど頻度が高い原因です。

手っ取り早い切り分けとして、コマンドパレットの「ドキュメントのフォーマット」（Format Document）を実行してみてください。ここで整形されるなら、フォーマッター自体は正常で formatOnSave の設定だけが問題だと分かります。整形されないなら、拡張機能か構文エラー側が原因です。

設定の競合が疑わしいときは、Ctrl+, の設定画面で formatOnSave と検索し、「ユーザー」と「ワークスペース」のタブを見比べます。ワークスペース設定はユーザー設定より優先されるため、プロジェクト側で切られているケースが見落とされがちです。

8.8 チームやCIと結果を揃える

1人で学習している間はエディターの設定だけで足りますが、他の人と同じコードを触るなら、整形ルールをプロジェクトのファイルに置いておくと安全です。BlackもRuffも pyproject.toml の設定を読みます。

[tool.black]
line-length = 100

[tool.ruff]
line-length = 100

こうしておけば、エディターから整形しても、ターミナルから black . や ruff format . を実行しても同じ結果になります。既存プロジェクトへ後から導入する場合は、最初の一括整形だけを独立したコミットに分けると、後から履歴を追う人が「中身の変更」と「整形だけの変更」を区別できます。

9. おすすめ settings.json 設定

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

9.1 ユーザー設定とワークスペース設定の違い

VSCodeの設定は2層構造です。ここを理解しておくと、「家では効いていた設定が、このプロジェクトでは効かない」の理由がすぐ分かります。

ユーザー設定ファイルの実体は、Windows なら %APPDATA%\Code\User\settings.json、macOS なら ~/Library/Application Support/Code/User/settings.json、Linux なら ~/.config/Code/User/settings.json です。とはいえ手で探す必要はほぼなく、コマンドパレットから開くのが確実です。

9.2 まず入れておきたいユーザー設定

次の内容は、Pythonを学び始めた時点でそのまま使える構成です。コメント付きで貼れるよう、行ごとに意味を添えています（settings.json は // のコメントを書ける形式です）。

{
  // エディター基本設定
  "editor.fontSize": 14,
  "editor.tabSize": 4,
  "editor.insertSpaces": true,
  "editor.wordWrap": "on",
  "editor.minimap.enabled": false,
  "editor.rulers": [88],
  "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"
}

1点だけ前提があります。source.organizeImports は import の並べ替えを担当する拡張機能（Black構成なら ms-python.isort）が入っていないと何も起きません。この行を活かすなら isort 拡張もあわせて導入してください。詳しくは8.6で解説しています。

9.3 プロジェクト側に置くワークスペース設定

使うPythonや整形ルールは、プロジェクト側に置いたほうが事故が減ります。.vscode/settings.json は手で作って構いません。.vscode フォルダーごと自分で作り、その中にこのファイルを置けば読み込まれます（VSCode側の操作で自動生成されることもあります）。

{
  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter",
    "editor.formatOnSave": true
  },
  "python.testing.pytestEnabled": true,
  "python.testing.pytestArgs": ["tests"],
  "files.exclude": {
    "**/__pycache__": true
  }
}

files.exclude はエクスプローラーの表示から隠す設定です。__pycache__ を隠すだけで、ファイル一覧がぐっと読みやすくなります。

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

全部覚える必要はありません。最初の1週間は下の「編集の基本」だけで十分です。手が勝手に動くようになったら次の表へ進んでください。マウスに戻る回数が減るほど、書く速度より「試す速度」が上がります。

編集の基本

移動と検索

Python開発で効くもの

覚え方のコツは、「マウスでやった操作を1つだけキーに置き換える」を毎日続けることです。キー割り当てはコマンドパレットの「基本設定: キーボードショートカット」から確認・変更できます。

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

VSCodeはカスタマイズ自由度が高いため、人によって生産性が大きく変わります。ここではPython開発を始めたばかりの方向けに、最初に押さえておくと差がつく実践テクニックを紹介します。環境の連携（§4）とデバッグ構成（§7）は済んでいる前提です。

11.1 .gitignore は最初に作る

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

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

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

# IDE（.vscode には共有したいファイルもあるので、丸ごとは無視しない）
# ローカル固有の設定まで共有したくない場合だけ、次の行のコメントを外す
# .vscode/settings.json
.idea/

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

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

ひとつ注意点があります。.gitignore でコメントとして扱われるのは行頭の # だけで、行の途中に書いた # はパターンの一部になります。.venv/ # 仮想環境 のように書くと「.venv/ # 仮想環境 という名前のもの」を探しにいくため、書いたのに無視されないという分かりにくい事故になります。注釈は必ず独立した行に書いてください。なお .vscode/settings.json を除外するかどうかは中身しだいなので、判断の基準は11.3にまとめました。

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

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

ターミナルは + ボタンで複数開けます。「実行用」と「pip install 用」を分けておくと、実行中のプログラムを止めずにライブラリを追加できます。分割表示アイコンで左右に並べれば、両方を同時に見られます。

11.3 .vscode フォルダーは何を共有するか

チームでリポジトリを共有するとき、.vscode の中身をコミットすべきか迷います。判断基準は「機械が違っても意味を持つか」です。

{
  "recommendations": [
    "ms-python.python",
    "ms-python.black-formatter"
  ]
}

これを置いておくと、そのフォルダーを初めて開いた人に「推奨拡張機能をインストールしますか」と案内が出ます。読者が自分1人でも、PCを買い替えたときの自分への引き継ぎとして役に立ちます。

11.4 テストの実行もVSCodeから

関数を書くようになったら、テストの自動実行を覚えると学習効率が変わります。フラスコのアイコン（テスト）から pytest を有効にすると、テスト関数の横に再生ボタンが出て、1つずつ実行できます。設定は §9 のワークスペース設定に書いた python.testing.pytestEnabled と python.testing.pytestArgs の2行です。

「変更する → テストを走らせる → 緑になる」のループが速くなるほど、思い切ってコードを直せるようになります。

12. よくあるトラブルと対処（症状別の逆引き）

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

12.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」）してください。

自作モジュールだけが解決できない場合は、importの基準になるフォルダーがずれています。src フォルダーの中にコードを置いている構成などでは、ワークスペース設定に解析対象のパスを足すとPylanceが認識します。

{
  "python.analysis.extraPaths": ["src"]
}

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

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

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

12.3 「Linter / Formatter が動かない」

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

対処：(1) フォーマッターの拡張機能が入っているか（ms-python.black-formatter または charliermarsh.ruff。本体は拡張に同梱されているため pip install は必須ではありません）、(2) settings.json の "[python]" の中に "editor.formatOnSave": true と "editor.defaultFormatter" があるか、(3) 右下の言語モードが「Python」になっているかを確認します。詳しい手順は§8.7の確認順にまとめました。

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

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

対処：GitHub Copilot などが出すインライン候補がIMEと衝突しているケースがあります。設定で「inline suggest」や「IME」を検索し、関連オプションを一時的にオフにして再現するか確かめてください。改善しない場合はVSCodeを最新版にアップデートすると解決することが多いです。

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

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

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

12.6 「python は認識されていません」とターミナルに出る

症状：ターミナルで python と打つと「'python' は、内部コマンドまたは外部コマンド…として認識されていません」と表示される。Microsoft Store が勝手に開く場合もあります。

原因：Python本体が入っていないか、入っていてもPATHに登録されていません。VSCodeの問題ではなく、Python側の設定です。

対処：Windows では py --version を試してください。これが通るならPython自体はあり、python というコマンド名が通っていないだけです。py -m pip install ... のように py 経由で使うか、インストーラーを再実行して「Add python.exe to PATH」を有効にします。詳細はPythonインストールのトラブル対処にまとめています。Store のインストール画面が開く場合は、設定の「アプリ実行エイリアス」で python の項目をオフにすると止まります。

12.7 デバッグが止まらない／止まりすぎる

症状A（止まらない）：ブレークポイントを置いたのに素通りして終了する。赤丸が白い輪郭（灰色）に変わっていることがあります。

原因と対処：その行が実行されていない、または実行しているファイルが別というのが大半です。launch.json の program が ${file} なら「いま開いているファイル」が対象なので、別のファイルを開いたまま F5 を押していないか確認してください。関数の中に置いたブレークポイントは、その関数が呼ばれなければ止まりません。まず if __name__ == "__main__": の直後など、確実に通る行で試すと切り分けられます。

症状B（止まりすぎる）：ライブラリの内部やまったく身に覚えのないファイルで停止してしまう。

原因と対処：justMyCode が false になっていると、標準ライブラリや外部ライブラリの中でも例外で停止します。自分のコードだけを追いたいときは true（省略時の既定）に戻してください。逆に、ライブラリの中で何が起きているか読みたいときだけ false にします。

もう1つ、「実行とデバッグ」パネルのブレークポイント一覧で「Raised Exceptions（発生した例外）」にチェックが入っていると、処理として握りつぶされている例外でも毎回止まります。覚えのない場所で止まるときはここも見てください。

13. よくある質問