Python デバッグ実習
uv と VS Code で
Python をデバッグ
Visual Studio で慣れたデバッグ操作を uv と VS Code でも使えるようにします。環境を設定し、ブレークポイントで変数を確認してコードを修正するまでの手順です。
図は操作を説明するための模式図です。
使う Python と起動するファイルは初回に指定します。コードを修正するたびに環境を作り直す必要はありません。
Visual Studio との対応
VS Code でもブレークポイントや変数の確認、ステップ実行ができます。Visual Studio と比べて戸惑いやすいのは実行環境を選ぶ手順です。環境の準備は uv で行い、使用する Python の選択とデバッグ起動は VS Code で行います。
uv syncプロジェクト専用の Python とライブラリを .venv にそろえます。Python: Select Interpreterこのフォルダーで使う Python として .venv 内の Python を選びます。.vscode/launch.json指定した Python で main.py を起動し、途中で止めます。| Visual Studio での考え方 | この教材での対応 |
|---|---|
| ソリューション/プロジェクトを開く | pyproject.toml があるフォルダーを VS Code で開く |
| ターゲットの .NET・実行環境 | プロジェクト用の Python(今回は 3.13)を選ぶ |
| NuGet の依存関係を復元 | uv sync で必要なライブラリを環境にそろえる |
| スタートアッププロジェクト | launch.json に起動先 main.py を固定する |
| F5・ローカル変数・ウォッチ | F5・「変数」・「ウォッチ」で同じように調べる |
仕組みが完全に同じという意味ではなく、役割を理解するための対応表です。たとえば .venv は Python の実行ファイルとライブラリをまとめた専用フォルダーです。
Python の実行とビルド
今回のような通常の Python スクリプトでは実行前のビルド操作は不要です。Python が保存済みの .py を読み込んで実行します。内部でバイトコードに変換されることはありますが、この実習で操作する必要はありません。
| 操作 | 役割 |
|---|---|
uv sync | 環境を準備・同期します。コードをビルドする操作ではありません。 |
uv run main.py | 通常実行です。これだけでは VS Code のブレークポイントで停止しません。 |
| VS Code の F5 | デバッグ実行です。この教材では .venv の Python をデバッガーから起動します。 |
uv build | パッケージの配布用ファイルを作成します。この実習では使いません。 |
必要なソフトウェアを確認する
VS Code と uv がインストール済みなら確認だけで進めます。Python 本体の準備には、次の章で uv を使います。
1-1. VS Code で作成先を開く
- Windows のエクスプローラーまたは Mac の Finder を開き、ドキュメントの中などに練習用の空フォルダー
python-practiceを作ります。 - Visual Studio Code を起動し、「ファイル」→「フォルダーを開く…」で
python-practiceを開きます。次の章ではこの中にpython-debug-demoを作ります。 - 信頼を確認する画面が出たら、自分で作ったこの練習用フォルダーを信頼します。すでに「制限モード」と表示されている場合は、その表示からワークスペースの信頼を管理できます。ドキュメント全体などに信頼する範囲を広げる必要はありません。
- 「ターミナル」→「新しいターミナル」を選びます。画面下部にコマンドを入力する欄が開きます。
Windowsこの教材では PowerShell を使います。ターミナルの一覧に PowerShell と表示されていれば次へ進みます。
macOSVS Code の統合ターミナルを使います。標準の zsh で進められます。
code . コマンドやその追加設定は不要です。VS Code をまだインストールしていない場合は、公式のダウンロードページから導入してください。1-2. uv が使えるか確認する
次の 1 行を入力して Enter を押します。コマンドの前に PS> や $ を付ける必要はありません。
uv --versionuv 0.x.x のようにバージョンが表示されます。数字は環境によって異なります。「見つからない」と表示されたら、uv の公式インストール手順で OS に合う方法を確認します。インストールした直後なら VS Code を終了して開き直し、新しいターミナルで再確認してください。
1-3. Python 拡張機能を確認する
- 拡張機能の検索欄に
@id:ms-python.pythonと入力します。 - 発行元が Microsoft の Python をインストールします。すでに有効ならそのままで構いません。
@id:ms-python.debugpyを検索し、Microsoft の Python Debugger が有効か確認します。通常は Python 拡張機能と一緒にインストールされます。
拡張機能は VS Code にインストールするものです。今回の方法では uv add debugpy を実行する必要はありません。Python Environments などの関連する拡張機能が一緒に入っていても構いません。
専用の Python 環境を作る
2-1. プロジェクトを作成する
次のコマンドを1 行ずつ実行します。エラーが出た場合は次の行に進まず、内容を確認してください。
uv init --no-package --python 3.13 python-debug-democd python-debug-demouv syncuv initは新しいプロジェクトを作成します。--no-packageを付けるとmain.pyから始める構成になります。--python 3.13で使う Python を 3.13 系にそろえます。必要な Python がなければ、通常は uv が取得します。cdは作成したフォルダーに移動するコマンドです。uv syncはプロジェクト専用の.venvと必要なライブラリを用意します。
cd の移動先も同じ名前にします。python-debug-demo の中に pyproject.toml、main.py、.venv、uv.lock ができています。2-2. 作成したプロジェクトを開き直す
- 作成した
python-debug-demoフォルダー自体を開きます。親フォルダーを開いたままにしないでください。 - フォルダーの信頼を確認する画面が出たら、自分で作成した内容であることを確認して信頼します。
- 左のエクスプローラーで
pyproject.tomlとmain.pyが直下にあることを確認します。
python-debug-demo/ ← このフォルダーを VS Code で開く ├─ .venv/ ← 専用の Python とライブラリ ├─ .python-version ← uv が使う Python バージョン ├─ main.py ← これから編集するプログラム ├─ pyproject.toml ← プロジェクトと依存関係の設定 └─ uv.lock ← 依存ライブラリの確定したバージョン
README.md や .gitignore なども作成されることがあります。この図では実習に関係するものを示しています。
2-3. このプロジェクトの Python を選ぶ
WindowsCtrl + Shift + P でコマンドパレットを開きます。
macOS⌘ + Shift + P でコマンドパレットを開きます。
main.pyをクリックして開きます。- コマンドパレットを開いて
Python: Select Interpreterと入力します。日本語 UI では「Python: インタープリターを選択」と表示されることもあります。 - このプロジェクト内の
.venvを選びます。「推奨」の表示だけで判断せず、パスにpython-debug-demoが含まれていることを確認します。
Windows の選択先python-debug-demo\.venv\Scripts\python.exe
macOS の選択先python-debug-demo/.venv/bin/python
候補にない場合は一覧を更新します。それでも見つからなければ「インタープリターパスを入力」などの項目から上の実行ファイルを指定します。macOS のファイル選択画面で隠しフォルダーが見えない場合は、⌘ + Shift + . で表示を切り替えられます。パスを直接入力しても構いません。
main.py を開くと、画面下のステータスバーに Python 3.13 系の .venv が表示されます。表示は拡張機能のバージョンによって異なるため、もう一度選択画面を開いてパスも確認すると確実です。この教材では手動で activate を実行する必要はありません。ターミナルでは
uv run を使い、デバッグでは VS Code が選択済みの Python を起動します。ターミナルの先頭に (.venv) が表示されるかどうかと、デバッグに使う Python の選択は分けて確認します。F5 で main.py を起動する
3-1. 練習用プログラムを入力する
main.py の内容をすべて次のコードに置き換えて保存します。練習用に割引を足してしまう間違いを 1 か所入れています。まずは直さずに使ってください。
def calculate_total(unit_price, quantity, discount):
subtotal = unit_price * quantity
total = subtotal + discount # 練習用の間違い:割引を足している
return total
def main():
unit_price = 1200
quantity = 3
discount = 300
total = calculate_total(unit_price, quantity, discount)
print(f"合計: {total:,} 円")
if __name__ == "__main__":
main()コピーボタンはコード本文だけをコピーします。ボタンでコピーできない場合はコードを選択して手動でコピーできます。
Windows保存は Ctrl + S です。
macOS保存は ⌘ + S です。
関数の中は半角スペース 4 個で字下げしています。空白も含めてコピーしてください。if __name__ == "__main__": は、このファイルから起動したときに main() を呼ぶ定番の書き方です。
3-2. .vscode/launch.json を作る
- エクスプローラーの余白を右クリックし、「新しいフォルダー」でプロジェクト直下に
.vscodeを作成します。先頭の.も必要です。 - 作成した
.vscodeを右クリックし、「新しいファイル」でlaunch.jsonを作成します。 - 次の設定を貼り付けて保存します。
{
"version": "0.2.0",
"configurations": [
{
"name": "Python: main.py をデバッグ",
"type": "debugpy",
"request": "launch",
"program": "${workspaceFolder}/main.py",
"console": "integratedTerminal",
"cwd": "${workspaceFolder}",
"justMyCode": true
}
]
}python-debug-demo/.vscode/launch.json に保存され、JSON の構文エラーが表示されていません。各設定の役割
| 設定 | 意味 |
|---|---|
name | デバッグ画面で選ぶ設定名です。 |
type: "debugpy" | Python Debugger を使います。古い解説の "python" ではなく "debugpy" を指定します。 |
request: "launch" | VS Code からプログラムを新しく起動します。 |
program | 起動先を main.py に固定します。${workspaceFolder} は VS Code で開いたフォルダーです。 |
console | print() の出力先を統合ターミナルにします。input() を追加した場合の入力先もここです。 |
cwd | 相対パスの基準になる作業フォルダーをプロジェクト直下にそろえます。 |
justMyCode | 通常のステップ実行では自分のコードを中心に追います。 |
python のパスを指定していないため、デバッガーは先ほど VS Code で選んだインタープリターを使います。この設定ファイルは Windows と macOS で共通です。
現在開いているファイルと起動するファイルは別です。自動生成された設定で
"program": "${file}" となっている場合は、現在開いているファイルを実行します。今回は Visual Studio のスタートアップ設定に近づけるため、起動先を main.py に固定しています。ブレークポイントで停止する
4-1. 3 行目にブレークポイントを置く
main.pyを開きます。- 3 行目の
total = subtotal + discountを探します。 - その行の行番号より左の余白をクリックします。赤い丸が付けば設定できています。空行やコメントだけの行ではなく、この計算行を選んでください。
4-2. 起動設定を選んで開始する
- 「実行とデバッグ」を開きます。アイコンが見つからない場合は「表示」メニューから「実行とデバッグ」を選びます。
- 画面上部の選択欄で「Python: main.py をデバッグ」を選びます。
- その横の緑の開始ボタン ▶を押すか、F5 を押します。
macOSF5 が音声入力などに反応する場合は Fn(地球儀キー)を押しながら F5 を押すか、画面上の開始ボタンを使います。F10・F11 も同様です。
- unit_price
- 1200
- quantity
- 3
- discount
- 300
- subtotal
- 3600
3 行目で停止した時点で、2 行目の計算は済んでいます。
subtotal は 3600 ですが、この関数の total にはまだ値が入っていません。変数一覧に total がなくても正常です。右上の ▶ で実行しても止まらない
変数の確認とステップ実行
3 行目で止まっている状態から始めます。すでに終了していたら、F5 でもう一度起動してください。
5-1. 変数一覧とマウスホバーで確認する
- 「変数」を展開し、必要なら「ローカル」も展開します。
unit_price = 1200、quantity = 3、discount = 300、subtotal = 3600を確認します。- コード内の
subtotalにマウスを重ねます。ここでも 3600 を確認できます。
5-2. ウォッチに本来の計算式を登録する
「ウォッチ」を展開し、見出し付近の + から次の式を入力して Enter を押します。
subtotal - discount5-3. デバッグコンソールで式を試す
下部のタブから「デバッグ コンソール」を選びます。見つからなければ「表示」メニューから開きます。入力欄に同じ subtotal - discount を入力して Enter を押すと、3300 と表示されます。
デバッグコンソールは停止中の変数を使って式を試す場所です。
uv sync などのコマンドやプログラムの input() に対する入力は「ターミナル」で行います。ここでは値を変える式ではなく、計算結果を確認する式だけを試します。5-4. F10 で計算行を実行する
- F10 を1 回だけ押します。画面の「ステップ オーバー」ボタンでも構いません。ボタンにマウスを重ねると操作名が分かります。
- 停止位置が 4 行目の
return totalに移動したことを確認します。 - 「変数」に
total = 3900が追加されたことを確認します。
| 確認するもの | 3 行目で停止中 | F10 を 1 回押した後 |
|---|---|---|
| 次に実行する行 | 3 行目:合計の計算 | 4 行目:return |
subtotal | 3600 | 3600 |
total | 未代入 | 3900 |
ウォッチの subtotal - discount | 3300 | 3300 |
小計は合っていますが、本来の合計 3300 に対して total は 3900 になっています。原因は3 行目で割引を足していることだと確認できました。
subtotal は calculate_total の中の変数です。関数から戻ると、ウォッチが「未定義」などの表示になることがあります。「コール スタック」で選択中のフレームが変わると、表示できる変数も変わります。これはエラーではなく、調べている場所が変わったためです。修正して再実行する
6-1. 続行して現在の結果を見る
4 行目で停止している状態から F5 を押すと、残りの処理が実行されてデバッグが終了します。「ターミナル」を選ぶと次の出力が表示されます。
F5 は開始前なら「デバッグの開始」、停止中なら「続行」です。終了後にもう一度押すと、プログラムは最初から動きます。
6-2. 3 行目を修正して保存する
3 行目を次の行に置き換えます。+ を - に変更し、練習用のコメントも取り除きます。先頭の半角スペース 4 個は残してください。
total = subtotal - discountファイルを保存します。まだデバッグ中なら、ツールバーの赤い四角「停止」で終了してから修正・再実行してください。停止中のプログラムに編集結果が自動で反映されることは前提にせず、起動し直して確認します。
6-3. F5 → F10 → F5 で確認する
- 3 行目のブレークポイントを残したまま F5 を押します。
- 3 行目で停止したら F10 を 1 回押し、
total = 3300を確認します。 - F5 で続行します。「ターミナル」の最新の出力を確認します。
6-4. F11 で関数の中に入る
Visual Studio の「ステップ イン」も試します。修正済みのコードで続けて構いません。
- デバッグが終了した状態で 3 行目の赤い丸をクリックして解除します。
- 11 行目の
total = calculate_total(unit_price, quantity, discount)にブレークポイントを置きます。 - F5 で 11 行目に停止したら、F11(ステップ イン)を押します。
calculate_total内の2 行目に移動します。この時点ではsubtotalにまだ値が入っていません。- F10 を押すと小計の計算が済み、3 行目に移動します。
subtotal = 3600を確認します。 - F5 で最後まで続行します。
| 操作 | キー | 何が起きるか |
|---|---|---|
| 開始/続行 | F5 | 起動する、または次のブレークポイント・終了まで進む |
| ステップ オーバー | F10 | 現在の行を実行して次へ。関数呼び出しは通常その中に入らず進む |
| ステップ イン | F11 | 関数呼び出しから、その関数の中へ入る |
| ステップ アウト | Shift + F11 | 現在の関数の残りを実行し、呼び出し元へ戻る |
| 停止 | Shift + F5 | 今回のデバッグ実行を終了する |
表のキーは既定の割り当てです。Mac の Fn キーや OS のショートカット、カスタムキーバインドの影響で動作が異なる場合は、ツールバーのボタンを使ってください。F10 や F11 の実行中でも、別のブレークポイントに達するとそこで止まることがあります。
日々の操作と新規プロジェクト
同じプロジェクトを続けるとき
VS Code で python-debug-demo を開き、必要な場所にブレークポイントを置きます。起動設定が「Python: main.py をデバッグ」になっていれば、毎回 launch.json を作り直す必要はありません。
コードだけを変更した場合は、毎回 uv sync を実行する必要はありません。この設定で F5 を押すと、uv ではなく準備済みの .venv の Python がデバッグ起動します。
新しいプロジェクトを作るとき
プロジェクト名を変えて同じ手順を繰り返します。今のプロジェクト内ではなく、新しいプロジェクトを置く親フォルダーで始めます。
uv init --no-package --python 3.13 my-next-appcd my-next-appuv sync起動ファイル名を変えた場合だけ launch.json の program も変更します。チェック欄はこのページ上の確認用で、再読み込みするとリセットされます。
ライブラリを追加するとき・環境を復元するとき
| 状況 | 操作と意味 |
|---|---|
| 外部ライブラリを追加 | プロジェクト直下で uv add パッケージ名。たとえば uv add requests は依存関係を記録し、通常は環境も更新します。この実習では追加不要です。 |
| 他の PC で開く/依存関係の変更を受け取る | pyproject.toml のある場所で uv sync。その PC の .venv を作成・更新し、VS Code でも選び直します。 |
| デバッガーなしで動作を確認 | uv run main.py。ブレークポイントには止まらず実行します。 |
ソースコード、
pyproject.toml、uv.lock、.python-version、.vscode/launch.json を移動先へコピーし、そこで uv sync を実行します。特に Windows と macOS では Python の実行ファイルやライブラリが異なります。症状別の確認手順
該当する項目を開いてください。多くの場合は、開いているフォルダー、選択した Python、実行ボタンのいずれかを確認すると原因を絞れます。
F5 で設定の選択画面が出る/保存した設定が見つからない
- 単独のファイルや親フォルダーではなく、
python-debug-demoフォルダー自体を開いているか確認します。 - プロジェクト直下の
.vscode/launch.jsonに設定を保存したか確認します。 - 「実行とデバッグ」で「Python: main.py をデバッグ」を選びます。
- Python Debugger がこのワークスペースで有効か確認します。
実行はできるがブレークポイントで止まらない
- 通常実行ボタンや
uv run main.pyではなく、F5 または「実行とデバッグ」の開始ボタンを使います。 - 3 行目など、実際に実行される処理のある行に赤い丸を付けます。
- ファイルを保存し、
programが編集しているmain.pyを指しているか確認します。 - ブレークポイントが無効化されていないか、「ブレークポイント」欄のチェックとツールバーを確認します。
実行中も丸が灰色・中抜きなら、丸にマウスを重ねて理由を確認します。起動前の色だけで判断しないでください。
.venv が候補に出ない/Python が見つからない
まずプロジェクト直下で uv sync が成功しているか確認します。その後、Python: Select Interpreter で一覧を更新するか、実行ファイルのパスを直接指定します。
Windows.venv\Scripts\python.exe
macOS.venv/bin/python
フォルダーを移動した場合や別の PC で開いた場合は、以前の選択先が残っていないか確認します。必要ならコマンドパレットの Developer: Reload Window でウィンドウを再読み込みします。
uv run では動くのに、F5 では ModuleNotFoundError になる
ターミナルとデバッガーが異なる Python を使っている可能性があります。VS Code でこのプロジェクトの .venv を選び直してください。次のコマンドをプロジェクト直下のターミナルで実行すると、uv が使う Python のパスを確認できます。
uv run python -c "import sys; print(sys.executable)"表示されたパスと VS Code の選択先を比べます。同じ環境なら、必要なライブラリが pyproject.toml に記録されているか確認して uv sync を実行します。新しく追加する場合は uv add を使います。この教材のサンプルには外部ライブラリは不要です。
F5・F10・F11 が別の機能を動かす
まずデバッグツールバーのボタンを使います。VS Code の「実行」メニューにも操作があります。キーボード設定や拡張機能によって割り当てが変わっている場合は、コマンドパレットの「キーボード ショートカットを開く」で確認できます。
macOSFn/地球儀キーを併用します。Mac のシステム設定でファンクションキーの動作を変える方法は、Apple の案内を参照してください。
Windowsノート PC の機種によっては Fn キーの併用が必要です。
total がない/ウォッチやコンソールで変数が未定義になる
停止した行はまだ実行されていません。最初に 3 行目で停止した時点で total がないのは正常です。F10 を 1 回押してから確認します。
subtotal を確認できるのは calculate_total のフレームです。「コール スタック」の選択先を確認してください。デバッグ終了後や関数から戻った後は、このローカル変数を評価できません。
修正したのに結果が変わらない/違うファイルが動く
ファイルを保存してデバッグを停止し、F5 で起動し直します。launch.json の program が目的のファイルを指しているか確認してください。ターミナルには過去の実行結果も残るため、末尾の新しい出力を見ます。
IndentationError・SyntaxError が表示される
main.py の全文をもう一度確認します。字下げの空白、半角の引用符、行末の : を保ってください。HTML のタイトルや行番号をコードに貼り付けないようにします。
launch.json では全角の引用符を使っていないか、カンマや括弧が不足していないか確認します。まずは掲載した全文をそのまま保存して試してください。
PowerShell に Activate.ps1 の実行ポリシーのエラーが出る
VS Code のターミナル自動有効化で出る場合があります。この教材のためにシステム全体の実行ポリシーを変える必要はありません。手動の activate は省き、コマンドは uv run を使います。デバッグは選択済み .venv の Python を使います。
まず uv --version と uv run main.py が実行できるか確認します。デバッグ自体が失敗する場合は、インタープリターの選択と実際のエラーメッセージを確認してください。
uv sync が失敗する/pyproject.toml が見つからない
ターミナルの現在位置が pyproject.toml のあるフォルダーか確認します。フォルダーを開き直した後は、新しいターミナルを開くと現在位置を確認しやすくなります。
ダウンロードや接続のエラーなら、通信環境や会社のプロキシ設定を確認します。Python やライブラリを取得できていなければ、後からデバッグの設定をしても解決しません。証明書の検証を無効化するのではなく、環境に合った設定を確認してください。
ローカル HTML の「コピー」が動かない
ブラウザーによってはローカルファイルからのクリップボード操作が制限されます。ボタンを押してコードが選択されたら、Windows は Ctrl+C、macOS は ⌘C でコピーしてください。選択されない場合は、コード本文をマウスで選択してコピーできます。
公式資料と検証した範囲
本文はこのページだけで読めます。詳しい説明や更新された情報を確認するときは、次のリンクを使ってください。
- VS Code:Python debuggingPython Debugger、launch.json、選択した Python、起動方法。
- VS Code:Python environments環境の選択、.venv の検出と管理。
- VS Code:Debug codeブレークポイント、変数、ウォッチ、ステップ実行。
- VS Code:Workspace Trust初めて開くフォルダーの信頼確認と制限モード。
- uv:Creating projectsuv init と --no-package の役割。
- uv:Working on projectsuv sync、uv add、uv run、配布用ビルド。
- Apple:Mac でファンクションキーを使う方法Fn/地球儀キーとファンクションキーの設定。
対象はローカルで動く単一の Python プロジェクトです。Web アプリ、テストのデバッグ、配布、リモート環境は扱いません。
Windows で uv によるプロジェクト作成、環境同期、サンプル実行を検証しました。修正前に 3,900 円、修正後に 3,300 円になることを確認済みです。VS Code の画面でも F5 による停止、変数の表示、F10・F11 によるステップ実行を確認しました。検証環境は uv 0.10.7、Python 3.13.12、Python Debugger 2026.6.0 です。
macOS の手順は公式資料に基づいており、実機では検証していません。
VS Code のテーマや表示言語、拡張機能のバージョンによってラベルや配置が多少異なります。図は操作位置を示す模式図です。確認日:2026 年 11 月 16 日。