Visual Studio でPython コードをデバッグする

Visual Studioは、Pythonの包括的なデバッグエクスペリエンスを提供します。この記事では、実行中のプロセスにデバッガーをアタッチし、 ウォッチ ウィンドウと イミディエイト ウィンドウで式を評価する方法について説明します。デバッガーでは、ローカル変数の検査、ブレークポイントの使用、ステートメントのステップイン/アウト/オーバー、 次のステートメントの設定などを行うことができます。

シナリオ固有のデバッグ情報については、次の記事を参照してください。

前提条件

Python ワークロードをサポートしてインストールされた Visual Studio。詳細については、「 Visual Studio での Python サポートのインストール」を参照してください。
デバッガーで使用するPythonのコード。

プロジェクトの有無にかかわらずコードをデバッグする

Python環境と引数を制御する場合は、まずコードのプロジェクトを作成します。 From existing Python code プロジェクトテンプレートを使用してプロジェクトを作成できます。詳細については、「既存のPython コードファイルからプロジェクトを作成するを参照してください。

ただし、Python コードをデバッグするために、Visual Studioにプロジェクトまたはソリューションファイルは必要ありません。スタンドアロン Python ファイルでコードをデバッグするには、Visual Studioでファイルを開き、Debug>Start Debugging を選択します。 Visual Studioは、グローバルな既定の環境で、引数なしでスクリプトを起動します。その後、コードの完全なデバッグサポートが提供されます。詳細については、「Python環境」を参照してください。

基本的なデバッグを調べる

基本的なデバッグワークフローには、ブレークポイントの設定、コードのステップ実行、値の検査、例外の処理が含まれます。デバッグセッションを開始する場合は、 デバッグ>デバッグの開始 を選択するか、 F5 キーボードショートカットを使用します。 projectの場合、これらのアクションは、projectのアクティブな環境と、Project Properties に指定されたコマンドライン引数または検索パスを使用して、startup ファイルを起動します。プロパティを構成するには、「プロジェクトのデバッグオプションを設定する」を参照してください。

プロジェクトのスタートアップファイルを設定する

プロジェクトのスタートアップファイルは、ソリューションエクスプローラー で太字で表示されます。スタートアップファイルとして使用するファイルを選択できます。

プロジェクトファイルをスタートアップファイルとして指定するには、ファイルを右クリックし、[ スタートアップ項目として設定] を選択します。

Visual Studio 2017 バージョン 15.6 以降では、指定したスタートアップファイルセットがない場合はアラートが表示されます。以前のバージョンのVisual Studioでは、Python インタープリターが実行されている Output ウィンドウ、または Output ウィンドウが一時的に開いて閉じる場合があります。

アクティブな環境を指定する

プロジェクトファイルを使用している場合、デバッガーは常にプロジェクトのアクティブなPython環境で開始します。現在アクティブな環境を変更できます。詳細については、「プロジェクトのPython環境を選択するを参照してください。

スタンドアロンのPythonコードファイルをデバッグする場合、Visual Studioはグローバルな既定の環境で、引数なしでスクリプトを起動します。

ブレークポイントを設定する

ブレークポイントは、プログラムの状態を調べることができるように、マークされたポイントでコードの実行を停止します。

Pythonの一部のブレークポイントは、他のプログラミング言語で作業した開発者にとっては驚くかもしれません。 Pythonでは、ファイル全体が実行可能コードであるため、Pythonは、最上位クラスまたは関数定義を処理するために読み込まれたファイルを実行します。ブレークポイントが設定されている場合、デバッガーがクラス宣言を途中で中断している可能性があります。この動作は正しいですが、驚くことがあります。

ブレークポイントを設定するには、コードエディターの左側の余白で選択するか、コード行を右クリックして [ ブレークポイント>ブレークポイントの挿入] を選択します。ブレークポイントが設定されている各行に赤い点が表示されます。
ブレークポイントを削除するには、赤い点を選択するか、コード行を右クリックし、[ ブレークポイント>ブレークポイントの削除] を選択します。また、赤い点を選択し、[ブレークポイント] を選択 して [ブレークポイント>ブレークポイントを無効にすることで、ブレークポイントを無効にすることもできます。

コードファイルの左余白でブレークポイントを無効にする方法を示すスクリーンショットのVisual Studio.

条件とアクションを設定する

ブレークポイントがトリガーされる条件 (変数が特定の値または値の範囲に設定されている場合にのみ中断するなど) をカスタマイズできます。

条件を設定するには、ブレークポイントの赤い点を右クリックし、[ 条件] を選択します。 [ ブレークポイントの設定] ダイアログが開きます。

ダイアログで、複数の条件を追加し、Pythonコードを使用して条件式を作成できます。 Visual Studioのこの機能の詳細については、「Breakpoint 条件を参照してください。

Visual Studioでブレークポイントの条件を構成するオプションを選択する方法を示すスクリーンショットです。
ブレークポイントの アクション を設定するオプションもあります。 [出力] ウィンドウにログを記録するメッセージを作成し、必要に応じて自動的に実行を続行するように指定できます。

Visual Studioでブレークポイントのトレースポイントアクションを作成する方法を示すスクリーンショット。

メッセージをログに記録すると、アプリケーションにログコードを直接追加しない トレースポイント が作成されます。

ブレークポイントの条件とアクションの構成方法に応じて、左側の余白の赤いアイコンが設定を示すように変わります。ドットの形、クロックタイマー、またはひし形が表示される場合があります。

コードをステップ実行する

Visual Studio がブレークポイントでコードの実行を停止する場合、コードをステップ実行したり、コードブロックを実行したりしてから、もう一度中断するために使用できるコマンドがいくつかあります。コマンドは Visual Studio のいくつかの場所で使用できます。たとえば、デバッガー ツールバー、デバッグ メニュー、コードエディターの右クリックコンテキストメニュー、キーボードショートカットを使用できます。

次の表に、これらのコマンドの概要とキーボードショートカットを示します。

命令	Shortcut	説明
止める	Shift + F5	デバッグセッションを停止します。
再起動	Ctrl + Shift + F5	現在のデバッグセッションを再起動します。
続行	F5	次のブレークポイントに到達するまでコードを実行します。
ステップインする	F11	次のステートメントを実行して停止します。次のステートメントが関数の呼び出しである場合、デバッガーは呼び出された関数の最初の行で停止します。
ステップオーバー	F10	関数の呼び出し (すべてのコードを実行する) や戻り値の適用など、次のステートメントを実行します。このコマンドを使用すると、デバッグする必要のない関数を簡単にスキップできます。
ステップアウトする	+	現在の関数が終了するまでコードを実行し、呼び出し元のステートメントにステップ実行します。このコマンドは、現在の関数の残りの部分をデバッグする必要がない場合に便利です。
カーソルまで実行	+	エディターでキャレットの場所までコードを実行します。このコマンドを使用すると、デバッグする必要のないコードのセグメントを簡単にスキップできます。
次のステートメントの設定	+ + F10	コード内の現在の実行ポイントをキャレットの場所に変更します。このコマンドを使用すると、コードに問題があることがわかっている場合や、望ましくない副作用が発生した場合など、コードのセグメントをまったく実行しないようにすることができます。
次のステートメントのを表示する	Alt+Num+\	コードで実行する次のステートメントに戻ります。このコマンドは、デバッガーが停止しているコード内の場所を見つけるのに役立ちます。

値の検査と変更

デバッガーでコードの実行を停止すると、変数の値を調べて変更できます。ウォッチ ウィンドウを 使用して、個々の変数とカスタム式を監視することもできます。詳細については、「変数の検査」を参照してください。

デバッグ中に データヒント 機能を使用して値を表示するには、エディター内の任意の変数にマウスポインターを合わせます。変数の値を選択して変更できます。

Autos ウィンドウを使用するには、Debug>Windows>Autos を選択します。このウィンドウには、現在のステートメントに近い変数と式が含まれています。値列をダブルクリックするか、 F2 キーを押して値を編集します。

[自動変数] ウィンドウの使用方法の詳細については、「自動変数とローカル」ウィンドウの「変数を検査する」を参照してください。

Locals ウィンドウを使用するには、Debug>Windows>Locals を選択します。このウィンドウには、現在のスコープ内にあるすべての変数が表示されます。値列をダブルクリックするか、 F2 キーを押して値を編集します。

[ローカル] ウィンドウの使用方法の詳細については、「自動変数とローカル」ウィンドウの「変数を検査する」を参照してください。
Watch ウィンドウを使用するには、Debug>Windows>Watch>Watch 1-4 を選択します。このオプションを使用すると、任意のPython式を入力して結果を表示できます。式は、各ステップで再評価されます。

Visual Studio デバッガーのウォッチウィンドウを示すスクリーンショットです。

Visual Studio デバッガーのウォッチウィンドウを示すスクリーンショット

ウォッチウィンドウの使用方法の詳細については、「 ウォッチ 」ウィンドウと「クイックウォッチ」ウィンドウで変数にウォッチを設定するを参照してください。
文字列値を調べるには、[値] エントリの右側にある [表示] (虫眼鏡) を選択します。 str、unicode、bytes、およびbytearrayの種類はすべて検査に使用できます。

[ 表示] ドロップダウンメニューには、テキスト、HTML、XML、JSON の 4 つの視覚化オプションが表示されます。

Visual Studio デバッガーの「表示」虫眼鏡からビジュアライザーにアクセスする方法を示すスクリーンショット

視覚化を選択すると、選択した型に従って引用符で囲まれていない文字列値がポップアップダイアログに表示されます。文字列は、折り返しとスクロール、構文の強調表示、ツリービューで表示できます。これらの視覚化は、長い文字列と複雑な文字列に関する問題をデバッグするのに役立ちます。

例外を表示する

デバッグ中にプログラムでエラーが発生したが、例外ハンドラーがない場合、デバッガーは例外の時点で中断します。

Visual Studio デバッガーでハンドルされないエラーの例外ポップアップを示すスクリーンショット

エラーが発生した場合は、呼び出し履歴を含め、現在のプログラムの状態を調べることができます。ただし、コードをステップ実行すると、デバッグ処理は例外が処理されるまで、またはプログラムが終了するまで例外を投げ続けます。

例外の展開ビューを表示するには、Debug>Windows>Exception 設定 を選択します。

Visual Studio デバッガーの「例外設定」ウィンドウを示すスクリーンショット

例外設定ウィンドウで、例外の次のチェックボックスは、その例外が発生したときにデバッガーが常に中断するかどうかを制御します。
特定の例外に対してより頻繁に中断するには、[ 例外設定] ウィンドウで例外の横にあるチェックボックスをオンにします。
既定では、ほとんどの例外は、ソースコードで例外ハンドラーが見つからない場合に中断されます。この動作を変更するには、例外を右クリックし、[ ユーザーコードで処理されない場合に続行] オプションを 変更します。例外が発生したときに中断を減らすには、このオプションの選択を解除します。
例外設定ウィンドウに表示されない例外を構成するには、[追加] (プラス記号) を選択します。監視する例外の名前を入力します。名前は、例外の完全な名前と一致する必要があります。

プロジェクトのデバッグオプションを構成する

既定では、デバッガーはコマンドライン引数や特別なパスや条件なしで、標準のPythonランチャーを使用してプログラムを起動します。デバッグプロパティを設定することで、Python プロジェクトのスタートアップオプションを構成できます。

プロジェクトのデバッグプロパティにアクセスするには、ソリューションエクスプローラー で Python プロジェクトを右クリックし、 Properties を選択し、 Debug タブを選択します。

Visual Studio debugger.

次のセクションでは、特定のプロパティについて説明します。

起動動作を定義する

次の表に、 Launch mode プロパティで使用できる値を示します。デバッガーの起動動作を定義するには、このプロパティを使用します。

価値	説明
標準Pythonランチャー	CPython、IronPython、Stackless Python などのバリアントと互換性のある移植可能なPythonで記述されたデバッグコードを使用します。このオプションは、純粋なPython コードをデバッグするための最適なエクスペリエンスを提供します。実行中の `python.exe` プロセスにアタッチすると、このプロパティで指定されたランチャーが使用されます。このランチャーでは、CPython 用の混合モードデバッグも提供されます。これにより、C/C++コードとPythonコードの間をシームレスにステップ実行できます。
Web ランチャー	起動時に既定のブラウザーを起動し、テンプレートのデバッグを有効にします。詳細については、「 Web テンプレートのデバッグ」セクションを参照してください。
Django Web ランチャー	Web ランチャープロパティと同じ動作を実装しますが、Django 環境の場合は実装します。このオプションは、下位互換性の目的でのみ使用します。
IronPython (.NET) ランチャー	.NET デバッガーを使用します。これは IronPython でのみ機能しますが、C# やVisual Basicなど、.NET言語プロジェクト間のステップ実行が可能です。このランチャーは、IronPython をホストする実行中の.NET プロセスにアタッチする場合に使用されます。

実行動作を定義する

次の表では、デバッガーの実行動作を構成するために設定できるプロパティについて説明します。

Property	説明
検索パス	プロジェクトで使用Visual Studioファイルとフォルダーの検索パスを指定します。これらの値は、ソリューションエクスプローラーのプロジェクトの Search Paths ノードに表示される項目と一致します。このダイアログでは検索パスを指定できますが、フォルダーを参照したり、パスを相対フォームに自動的に変換したりできるソリューションエクスプローラーを使う方が簡単です。
スクリプト引数	スクリプトの起動に使用Visual Studioコマンドに追加する引数を定義し、スクリプトのファイル名の後に表示します。値に一覧表示されている最初の項目は、 `sys.argv[1]`としてスクリプトで使用でき、2 番目の項目は `sys.argv[2]` として使用できます。
インタープリター引数	スクリプトの名前の前にランチャーコマンドラインに追加する引数を一覧表示します。一般的な引数は、警告を制御する `-W ...` 、プログラムを少し最適化する `-O` 、バッファーなしの IO を使用する `-u` です。 IronPython ユーザーは、このフィールドを使用して、`-X`や`-X:Frames`などの`-X:MTA`オプションを渡す可能性があります。
インタープリターパス	現在の環境に関連付けられているパスをオーバーライドするインタープリターパスを識別します。この値は、非標準インタープリターを使用してスクリプトを起動する場合に役立ちます。
環境変数	フォーム `<NAME>=\<VALUE>`のエントリを追加するには、このプロパティを使用します。 Visual Studioは、このプロパティ値を既存のグローバル環境変数の上に最後に適用し、`PYTHONPATH` が Search Paths 設定に従って設定された後に適用されます。その結果、この設定を使用して、これらの他の変数のいずれかを手動でオーバーライドできます。

対話型ウィンドウを操作する

デバッグセッション中に使用できる interactive ウィンドウには、標準の Visual Studio Immediate ウィンドウと Python Debug Interactive ウィンドウの 2 つがあります。

イミディエイトウィンドウを開く

標準の Visual Studio Immediate ウィンドウを使用すると、Python式をすばやく評価し、実行中のプログラムで変数を検査または割り当てることができます。詳細については、「イミディエイトウィンドウ」を参照してください。

Immediate ウィンドウを開くには、Debug>Windows>Immediate を選択します。キーボードショートカット Ctrl+Alt+I を使用することもできます。

[デバッグ対話型] ウィンドウを開く

Python Debug Interactive ウィンドウには、コードの記述や実行など、デバッグ中に使用可能な完全な Interactive REPL エクスペリエンスを備えたリッチな環境が用意されています。このウィンドウは、Debug>Attach to Process を介してアタッチされたプロセスを含め、Standard Python ランチャーを使用してデバッガーで開始されたすべてのプロセスに自動的に接続します。ただし、混合モードの C/C++ デバッグを使用する場合、このウィンドウは使用できません。

Debug Interactive ウィンドウを使用するには、Debug>Windows>Python Debug Interactive を選択します (Shift+Alt+I)。

Visual StudioでPythonデバッグ対話型ウィンドウを操作する方法を示すスクリーンショット

デバッグ対話型ウィンドウでは、次の表に示すように、標準の REPL コマンドに加えて特殊なメタコマンドがサポートされます。

命令	説明
`$continue`、 `$cont`、 `$c`	現在のステートメントからプログラムの実行を開始します。
`$down`、`$d`	スタックトレースで現在のフレームを 1 レベル下に移動します。
`$frame`	現在のフレーム ID を表示します。
`$frame`	現在のフレームを指定したフレーム ID に切り替えます。 - <フレーム ID> 引数が必要です。
`$load`	ファイルからコマンドを読み込み、完了するまで実行します。
`$proc`	現在のプロセス ID を表示します。
`$proc`	現在のプロセスを指定したプロセス ID に切り替えます。 - <process ID> 引数が必要です。
`$procs`	現在デバッグ中のプロセスを一覧表示します。
`$stepin`、 `$step`、 `$s`	可能であれば、次の関数呼び出しにステップインします。
`$stepout`、 `$return`、 `$r`	現在の関数からステップアウトします。
`$stepover`、 `$until`、 `$unt`	次の関数呼び出しをステップオーバーします。
`$thread`	現在のスレッド ID を表示します。
`$thread`	現在のスレッドを指定したスレッド ID に切り替えます。 - <thread ID> 引数が必要です。
`$threads`	現在デバッグ中のスレッドを一覧表示します。
`$up`、`$u`	スタックトレースの現在のフレームを 1 レベル上に移動します。
`$where`、 `$w`、 `$bt`	現在のスレッドのフレームを一覧表示します。

プロセス、スレッド、呼び出し履歴などの標準デバッガーウィンドウは、[デバッグ対話型] ウィンドウと同期されません。 [デバッグ対話型] ウィンドウでアクティブなプロセス、スレッド、またはフレームを変更しても、他のデバッガーウィンドウは影響を受けません。同様に、他のデバッガーウィンドウでアクティブなプロセス、スレッド、またはフレームを変更しても、 デバッグ対話型 ウィンドウには影響しません。

レガシデバッガーを使用する

環境の構成によっては、レガシデバッガーの使用が必要になる場合があります。

Visual Studio 2017 バージョン 15.7 以前 (Python 2.6、3.1 から 3.4、または IronPython)
Visual Studio 2019 バージョン 16.5 以降 (Python 2.6、3.1 から 3.4、または IronPython)
ptvsd 3.x および 4.x の初期バージョン

レガシデバッガーは、Visual Studio 2017 バージョン 15.7 以前の既定です。

レガシデバッガーを使用するには、Tools>Options を選択します。 Python>Debugging オプションを展開し、 レガシデバッガー オプションを選択します。

古いVisual StudioまたはPythonバージョンをサポートする

Visual Studio 2017 バージョン 15.8 以降では、ptvsd バージョン 4.1 以降に基づくデバッガーを使用します。 Visual Studio 2019 バージョン 16.5 以降では、debugpy に基づくデバッガーを使用します。デバッガーのこれら 2 つのバージョンは、Python 2.7 以降Python 3.5 以降と互換性があります。

これらのバージョンの Visual Studio のいずれかを使用しているが、Python 2.6、3.1 から 3.4、または IronPython を使用している場合、Visual Studio はエラーを表示します: Debugger はこの Python 環境ではサポートされていません。

この環境エラー Visual Studio報告する場合は、レガシデバッガーを使用する必要があります。

以前の ptvsd バージョンをサポートする

現在の環境で以前のバージョンの ptvsd を使用している場合 (以前の 4.0.x バージョンや、リモートデバッグに必要な 3.x バージョンなど)、Visual Studioにエラーまたは警告が表示されることがあります。

環境で ptvsd 3.x を使用している場合、Visual Studio がエラーを表示します: Debugger パッケージを読み込めませんでした。

以前の 4.x バージョンの ptvsd を使用している場合、 デバッガーパッケージが古くなっているという警告が表示されます。

これらの環境エラー Visual Studio報告する場合は、レガシデバッガーを使用する必要があります。

Important

一部のバージョンの ptvsd の警告を無視することもできますが、Visual Studioは正常に動作しない可能性があります。

ptvsd のインストールを管理する

ptvsd インストールを管理するには、次の手順に従います。

Python環境 ウィンドウで、Packages タブに移動します。
検索ボックスに 「ptvsd 」と入力し、インストールされているバージョンの ptvsd を調べます。
バージョンが 4.1.1a9 (Visual Studio にバンドルされているバージョン) より低い場合は、パッケージの右側にある X を選択して、古いバージョンをアンインストールします。 Visual Studioバンドルされたバージョンを使用します。 ( pip uninstall ptvsd コマンドを使用して PowerShell からアンインストールすることもできます)。
または、「デバッグシナリオのトラブルシューティング」セクションの手順に従って、ptvsd パッケージを最新バージョンに更新することもできます。

デバッグシナリオのトラブルシューティング

次のシナリオでは、デバッグ構成のその他のトラブルシューティングオプションについて説明します。

Visual Studio 2019 用 ptvsd のアップグレード

Visual Studio 2019 バージョン 16.4 以前でデバッガーに問題がある場合は、まず次のようにデバッガーのバージョンをアップグレードします。

Python環境 ウィンドウで、Packages タブに移動します。
検索ボックスに 「ptvsd --upgrade 」と入力し、[ Run command: pip install ptvsd --upgrade] を選択します。 (PowerShell から同じコマンドを使用することもできます)。

問題が解決しない場合は、PTVS GitHub リポジトリに問題を提出します。

Note

Visual Studio 2019 バージョン 16.5 以降では、debugpy はVisual Studio Python ワークロードの一部であり、Visual Studioと共に更新されます。

デバッガーのログ記録を有効にする

デバッガーの問題を調査する過程で、Microsoftは診断に役立つデバッガーログを有効にして収集するように求められる場合があります。

次の手順では、現在のVisual Studio セッションでデバッグを有効にします。

Visual Studioでコマンドウィンドウを開くには、View>その他のWindows>コマンドウィンドウを選択します。

次のコマンドを入力します。

DebugAdapterHost.Logging /On /OutputWindow

デバッグを開始し、問題を再現するために必要な手順を実行します。この間、デバッグログは、[デバッグ アダプターホストログ] の [出力] ウィンドウに表示されます。その後、そのウィンドウからログをコピーし、GitHubの問題や電子メールなどを貼り付けることができます。
Visual Studio応答が停止した場合、または Output ウィンドウにアクセスできない場合は、Visual Studioを再起動してコマンドウィンドウを開き、次のコマンドを入力します。
```
DebugAdapterHost.Logging /On
```
デバッグを開始し、問題をもう一度再現します。デバッガーログは、 %temp%\DebugAdapterHostLog.txtにあります。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-05-08