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

[アーティクル]
04/18/2024

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

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

前提条件

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ブレークポイントを設定すると、マークしたポイントでコードの実行が停止するので、プログラムの状態を確認することができます。

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

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

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

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

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

ダイアログでは、Python コードを使用して複数の条件を追加し、条件式を作成できます。 Visual Studio のこの機能の詳細については、「Breakpoint conditions」 (ブレークポイント条件) を参照してください。
ブレークポイントの [アクション] を設定するオプションもあります。 [出力] ウィンドウにログを記録するメッセージを作成し、必要に応じて自動的に実行を続行するように指定できます。

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

ブレークポイントの条件とアクションをどのように構成するかによって、設定を示す左余白の赤いアイコンは変わります。ドット形状、クロックタイマー、またはひし形が表示される可能性があります。

コードのステップ実行

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

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

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

値の検査および変更

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

デバッグ中にデータヒント機能を使用して値を表示するには、エディター内で変数の上にマウスを合わせます。変数の値を選択して変更することができます。
[自動変数] ウィンドウを使用するには、[デバッグ]>[ウィンドウ]>[自動変数] を選択します。このウィンドウには、現在のステートメントに近い変数と式が表示されます。値を編集するには、値列をダブルクリックするか、値列を選択して F2 キーを入力します。

[自動変数] ウィンドウの使用方法の詳細については、「自動変数ウィンドウとローカルウィンドウで変数を検査する」を参照してください。
[ローカル] ウィンドウを使用するには、[デバッグ]>[ウィンドウ]>[ローカル] を選択します。このウィンドウには、現在のスコープ内のすべての変数が表示されます。ここでも値は編集できます。

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

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

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

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

例外を表示する

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

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

例外の展開ビューを表示するには、[デバッグ]>[ウィンドウ]>[例外設定] を選択します。

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

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

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

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

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

起動動作を定義する

次の表は、起動モード プロパティの入力可能値をまとめたものです。デバッガーの起動動作を定義するには、このプロパティを使用します。

Value	説明
標準的な 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 プロセスにアタッチする場合に使用されます。

実行動作を定義する

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

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

対話型ウィンドウを使用する

デバッグセッション中に使用できる対話型ウィンドウには、標準的な Visual Studio の [イミディエイト] ウィンドウと、[Python Debug Interactive] ウィンドウの 2 つがあります。

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

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

[イミディエイト] ウィンドウを開くには、[デバッグ]>[ウィンドウ]>[イミディエイト] を選択します。キーボードショートカット Ctrl+Alt+I を使用することもできます。

Debug Interactive ウィンドウを開く

[Python Debug Interactive] ウィンドウは、コードの記述や実行など、デバッグ中に利用できる完全な対話型 REPL エクスペリエンスを備えた充実した環境を提供します。このウィンドウは、標準的な Python ランチャーを使用して、デバッガー内で開始されているプロセスに自動的に接続します ([デバッグ]>[プロセスにアタッチ] でアタッチされたプロセスも含みます)。ただし、C/C++ の混合モードデバッグを使用している場合、このウィンドウは使用できません。

[Debug Interactive] ウィンドウを使用するには、[デバッグ]>[ウィンドウ]>[Python Debug Interactive] (Shift+Alt+I)] を選択します。

[Debug Interactive] ウィンドウでは、次の表に示すように、標準 REPL コマンドに加えて、特別なメタコマンドがサポートされています。

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

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

レガシデバッガーを使用します

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

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

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

レガシデバッガーを使用するには、[ツール]>[オプション] を選択し、[Python]>[デバッグ] オプションを展開して、[レガシデバッガーを使用] オプションを選択します。

前のバージョンの Visual Studio または Phthon をサポートする

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 には、"デバッガーではこの Python 環境はサポートされていません" というエラーが表示されます。

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

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

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

環境で ptvsd 3.x を使用している場合、Visual Studio には、"デバッガーパッケージを読み込めませんでした" というエラーが表示されます。

初期 4.x バージョンの ptvsd を使用している場合、"デバッガーパッケージが最新ではありません" という警告が表示されます。

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

重要

ptvsd の一部のバージョンについては警告を無視してかまわない場合もありますが、Visual Studio が正しく動作しない可能性はあります。

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

次の手順に沿って、ptvsd のインストールを管理します。

[Python 環境] ウィンドウの [パッケージ] タブに移動します。
検索ボックスに「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 環境] ウィンドウの [パッケージ] タブに移動します。
検索ボックスに「ptvsd --upgrade」と入力して、[次のコマンドを実行する: pip install ptvsd --upgrade] を選択します (PowerShell から同じコマンドを使用することもできます)。

問題が解決しない場合は、PTVS GitHub リポジトリで問題を報告します。

Note

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

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

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

次の手順により、現在の Visual Studio セッションでのデバッグが有効になります。

[ビュー]>[他のウィンドウ]>[コマンドウィンドウ] を選択して、Visual Studio でコマンドウィンドウを開きます。

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

DebugAdapterHost.Logging /On /OutputWindow

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

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

前提条件

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