はじめてのVSCodeデバッグ(Python): ステップ実行と変数ウォッチ

2025年9月23日

Python

VSCodeのデバッガは、プログラムを止めて中身をのぞきながら原因を探せる強力なツールです。

本記事ではPython初心者の方でも迷わないように、VSCode標準の「Run and Debug」を使って、ブレークポイントの設定、ステップ実行、変数ウォッチ、例外での中断までを順を追って丁寧に解説します。

print()デバッグから、正確で再現性のあるデバッグへステップアップしましょう。

VSCodeでPythonデバッグを始める準備
ブレークポイントの置き方とデバッグ開始
ステップ実行の基本操作(Python)
変数の確認とウォッチ
まとめ

VSCodeでPythonデバッグを始める準備

必要なもの(Python/VSCode/Python拡張)

概要

Pythonのデバッグを開始するには、以下の3点が必要です。

どれも無料で準備できます。

特にVSCodeのPython拡張は必須です。

Python本体(3.8以上を推奨)
Visual Studio Code(最新版)
VSCode拡張機能「Python」(Microsoft製)

インストールのチェック

Pythonはターミナルでpython --versionまたはpython3 --versionを実行して確認します。

VSCodeの拡張は拡張ビューからPythonを検索し、Microsoftのものをインストールします。

拡張のインストール後はVSCodeの再起動を行うと認識が安定します。

Pythonインタープリタを選ぶ(venv可)

venvを作る

プロジェクトごとに環境を分けると依存関係が衝突しにくくなります。

標準のvenvで仮想環境を作成しましょう。

Shell

# 例: カレントディレクトリに .venv を作る
python -m venv .venv

# Windows: 仮想環境を有効化
.venv\Scripts\activate

# macOS/Linux: 仮想環境を有効化
source .venv/bin/activate

# 必要なパッケージがあればここで pip install
pip install requests  # 例

VSCodeでインタープリタを選択

VSCode左下のステータスバーに表示されるPython 3.x部分をクリックし、.venvのインタープリタを選びます。

見当たらない場合はコマンドパレットでPython: Select Interpreterを実行します。

デバッグは選択中のインタープリタで実行されるため、ここは最初に確認しておきます。

サンプルコードを用意(簡単な関数)

サンプルのねらい

次のサンプルは、複数の関数呼び出し(ステップイン/アウトの練習)と、ゼロ除算の例外(例外で中断の練習)、条件付きブレークポイントやログポイントに適した変数(インデックスと値)を含みます。

以下のdebug_sample.pyを作成します。

Python

# debug_sample.py
# 目的:
# - ステップ実行(F10/F11/Shift+F11)の練習
# - 条件付きブレークポイント(例: v == 0)
# - ログポイント(ループ中の変数を出力)
# - 例外で中断(ZeroDivisionError を Raised/Uncaught で止める)
from typing import List, Optional

def reciprocal(x: float) -> float:
    # 0 のときは ZeroDivisionError が発生
    return 1 / x

def to_reciprocals(values: List[float]) -> List[Optional[float]]:
    result: List[Optional[float]] = []
    for i, v in enumerate(values):
        try:
            r = reciprocal(v)  # ここにブレークポイントを置くと効果的
        except ZeroDivisionError:
            # 例外は捕捉するが、Raised Exceptions を有効にすると raise 直後に止まれる
            r = None
        result.append(r)
    return result

def average_non_none(values: List[Optional[float]]) -> float:
    total = 0.0
    count = 0
    for v in values:
        if v is None:
            continue
        total += v
        count += 1
    # count が 0 のときは ZeroDivisionError になる(例外で中断の練習に使える)
    return total / count

def main() -> None:
    nums = [2, 1, 0, -4]  # 0 を含むので例外が発生するケースあり
    recips = to_reciprocals(nums)
    print("recips:", recips)
    avg = average_non_none(recips)
    print("average:", avg)

if __name__ == "__main__":
    main()

実行結果(通常実行時の標準出力の例):

text

recips: [0.5, 1.0, None, -0.25]
average: 0.4166666666666667

実行とデバッグビューを開く(Run and Debug)

開き方

アクティビティバーのRun and Debugアイコンを開くか、ショートカットCtrl+Shift+D(macOSはCmd+Shift+D)でデバッグビューを開きます。

初回は実行構成の選択ダイアログが表示されることがあります。

画面構成の理解

左ペインにVariables、Watch、Call Stack、Breakpointsが並び、下部にDebug Consoleが現れます。

これらがデバッグの主要ツールです。

構成は自動でOK(launch.jsonは不要)

自動構成を使う

実行とデバッグをクリックし、デバッグドロップダウンでPython Fileを選べば、launch.jsonを作らずにそのままデバッグ開始できます。

複雑な設定が必要になるまでは、この自動構成で十分です。

設定ファイルの書き方で悩む前に、まずはF5で動かしてみるのがおすすめです。

ブレークポイントの置き方とデバッグ開始

行番号横をクリックしてブレークポイント設定

手順

エディタの行番号左の余白をクリックすると赤い丸(ブレークポイント)が付きます。

Python拡張機能が未インストール、または無効化しているとブレークポイントは設定できません。必ずインストールして有効化しておきましょう。

サンプルではr = reciprocal(v)の行に置くと、ループ中に都度停止して確認できます。

ブレークポイントで停止中は、画像の上部にあるようなボタンが表示されます。

Continue (再開)F5 – プログラムを次のブレークポイントまで実行する。
Step Over (ステップオーバー)F10 – 次の行を実行し、関数呼び出しの中には入らない。
Step Into (ステップイン)F11 – 関数呼び出しの中に入って実行を進める。
Step Out (ステップアウト)Shift + F11 – 現在の関数の残りを実行して呼び出し元に戻る。
Restart (再起動)Ctrl + Shift + F5 – デバッグセッションを最初からやり直す。
Stop (停止) Shift + F5 – デバッグセッションを強制終了する

1行ずつデバッグしていきたい場合、ステップオーバーを繰り返すと、どの用に処理が行われているのか視覚的にわかるので、デバッグ初心者にはおすすめです。

デバッグボタンを押し間違えてもプログラムが破壊されるわけではないので、実際に触って挙動を確かめてみることをおすすめします。

F9でトグルも可能です。

補足

ブレークポイントは複数置けます。また、デバッグ中に新しいブレークポイントを置くことも可能です。

Breakpointsビューで一覧管理でき、チェックで有効/無効を切り替えられます。

デバッグ開始(F5)と停止

開始と停止

デバッグはF5で開始、Shift+F5で停止します。

macOSでファンクションキーが効かない場合はfnキー併用やキーバインドの確認を行ってください。

初回の挙動

初回は「Python File」選択ダイアログが出る場合があります。

選択後はデバッガが起動し、最初のブレークポイントで停止します。

実行の再開(Continue)と一時停止

使い分け

停止中にF5(Continue)で次のブレークポイントまで進みます。

逆に実行中に一時停止したいときは、デバッグツールバーのPauseボタンを押します。

意図しない無限ループを疑うときの強力な手段です。

条件付きブレークポイント(特定の値で止める)

設定方法

赤い丸を右クリックしてEdit BreakpointまたはAdd Conditional Breakpointを選び、条件式を入力します。

Pythonではi == 2やv == 0などが使えます。

条件がTrueになった時だけ停止するので、長いループの検証に有効です。

ヒント

条件式には任意の式が書けますが、副作用のある関数呼び出しは避けるのが安全です。

ログポイント(止めずにログ出力)

使い方

余白を右クリックしてAdd Logpointを選び、ログメッセージを入力します。

例:i={i}, v={v}。

ログポイントは実行を止めずにDebug Consoleに値を出力します。

print()を書き換える必要がなく、後始末も不要です。

注意点

ログポイントのメッセージ内では{変数名}で現在のローカル変数を参照できます。

重い処理を多数のループでログ出力すると実行が遅くなる点には注意します。

ステップ実行の基本操作(Python)

ショートカット早見(主要のみ)

操作	キー(既定)	説明
続行(Continue)	F5	次のブレークポイントまたは終了まで進む
停止(Stop)	Shift+F5	デバッグを終了
ステップオーバー	F10	現在行を実行し、同じフレームで次行へ
ステップイン	F11	関数呼び出しの中へ入る
ステップアウト	Shift+F11	現在の関数を最後まで実行し、呼び出し元へ戻る