Python コードのデバッグ

適用対象:yesVisual Studio noVisual Studio for Mac noVisual Studio Code

Visual Studio は、実行中のプロセスへのアタッチ、ウォッチ ウィンドウやイミディエイト ウィンドウでの式の評価、ローカル変数の調査、ブレークポイントの設定、ステートメントのステップ イン/ステップ アウト/ステップ オーバー、次のステートメントの設定など、Python 向けの総合的なデバッグ機能を提供します。

シナリオ固有のデバッグに関する次の記事も参照してください。

ヒント

Visual Studio の Python は、プロジェクトを使用しないデバッグをサポートしています。 スタンドアロンの Python ファイルを開き、エディター内で右クリックして、 [デバッグの開始] を選択すると、Visual Studio がグローバルな既定の環境 (「Python Environments」 (Python 環境) を参照) を使用して、引数なしでスクリプトを起動します。 ただし、それ以降は、フル機能のデバッグ サポートが提供されます。

環境と引数を制御するには、コードのプロジェクトを作成します。プロジェクトは、[既存の Python コードから] プロジェクト テンプレートを使用して簡単に作成できます。

デバッグの基本

デバッグの基本的なワークフローには、ブレークポイントの設定、コードのステップ実行、値の検査、例外の処理が含まれます。これらについては、後続のセクションで説明します。

デバッグ セッションを開始するには、 [デバッグ]>[デバッグの開始] コマンド、ツールバーの [開始] ボタン、または F5 キーを使用します。 これらの操作で、プロジェクトのアクティブな環境と、プロジェクトのプロパティで指定されているコマンドライン引数や検索パスを使用して、プロジェクトのスタートアップ ファイル (ソリューション エクスプローラーで太字で表示) が起動します (「プロジェクトのデバッグ オプション」を参照してください)。 Visual Studio 2017 バージョン 15.6 以降では、スタートアップ ファイルが設定されていない場合は警告が表示されます。それより前のバージョンでは、Python インタープリターが実行された出力ウィンドウが開くか、表示されても短時間で消えていきます。 どの場合も、適切なファイルを右クリックし、 [スタートアップ ファイルとして設定] を選びます。

Note

デバッガーは常に、プロジェクトのアクティブな Python 環境で起動します。 環境を変更するには、プロジェクト用の Python 環境の選択に関する記事の説明に従って、別の環境をアクティブにします。

ブレークポイント

ブレークポイントを設定すると、マークしたポイントでコードの実行が停止するので、プログラムの状態を確認することができます。 ブレークポイントを設定するには、コード エディターの左端の余白をクリックするか、コード行を右クリックして [ブレークポイント]>[ブレークポイントの挿入] を選択します。 ブレークポイントが設定された行には赤い点が表示されます。

Breakpoints appearing in Visual Studio

赤い点をクリックするか、コード行を右クリックして [ブレークポイント]>[ブレークポイントの削除] を選択すると、ブレークポイントが削除されます。 [ブレークポイント]>[ブレークポイントの無効化] コマンドを使用して、ブレークポイントを削除せずに無効にすることもできます。

Note

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

ブレークポイントをトリガーする条件は、カスタマイズすることができます。たとえば、変数が特定の値または値の範囲に設定されたときにのみ中断するなどです。 条件を設定するには、ブレークポイントの赤い点を右クリックして [条件] を選択し、Python コードを使用して式を作成します。 Visual Studio のこの機能の詳細については、「Breakpoint conditions」 (ブレークポイント条件) を参照してください。

条件を設定するときに、 [アクション] も設定することができます。出力ウィンドウに表示するメッセージを作成し、必要に応じて自動で実行を継続できます。 メッセージをログに記録すると、ログ コードを直接アプリケーションに導入しなくても、トレースポイントが作成されます。

Creating a tracepoint with a breakpoint

コードのステップ実行

ブレークポイントで停止したら、次に再び停止するまで、コードをさまざまな方法でステップ実行したり、コードのブロックを実行したりできます。 これらのコマンドは、上部の [デバッグ] ツールバー、 [デバッグ] メニュー、コード エディターの右クリック コンテキスト メニュー、ショートカット キーなど、さまざまな場所から利用できます (すべての場所ですべてのコマンドを利用できるわけではありません)。

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

値の検査および変更

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

データヒントを使用して値を表示するには、エディター内で変数の上にマウスを合わせます。 値を選択して変更することができます。

DataTips showing in the Visual Studio debugger

自動変数ウィンドウ ( [デバッグ]>[ウィンドウ]>[自動変数] ) には、現在のステートメントに近い変数と式が表示されます。 値を編集するには、値列をダブルクリックするか、値列を選択して F2 キーを押します。

Autos window in the Visual Studio debugger

ローカル ウィンドウ ( [デバッグ]>[ウィンドウ]>[ローカル] ) には、現在のスコープ内のすべての変数が表示されます。この値も編集できます。

Locals window in the Visual Studio debugger

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

ウォッチ ウィンドウ ( [デバッグ]>[ウィンドウ]>[ウォッチ]>[ウォッチ 1 ~ 4] ) では、任意の Python 式を入力して結果を表示できます。 式は、ステップごとに再評価されます。

Watch window in the Visual Studio debugger

ウォッチ ウィンドウの使用方法について詳しくは、「Setting a Watch on Variables using the Watch and QuickWatch Windows」 (ウォッチ ウィンドウとクイック ウォッチ ウィンドウを使用して変数のウォッチ ポイントを設定する) を参照してください。

文字列値 (ここでは、strunicodebytes および bytearray はすべて文字列と見なします) を検査する際、値の右側に虫眼鏡のアイコンが表示されます。 このアイコンを選択すると、ポップアップ ダイアログに引用符なしの文字列値が表示されます。改行およびスクロールされるので、長い文字列の場合に便利です。 さらに、このアイコンのドロップダウン矢印を選択すると、プレーン テキスト、HTML、XML、または JSON のビジュアライザーを選択できます。

String visualizers in the Visual Studio debugger

HTML、XML、JSON のビジュアライザーは別のポップアップ ウィンドウに表示されます。構文が強調表示され、ツリー ビューで表示されます。

例外

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

Exception popup in the Visual Studio debugger

ここで、呼び出し履歴を含めたプログラムの状態を検査することができます。 しかし、コードのステップ実行を試みると、例外は、処理されるかプログラムが終了するまでスローされ続けます。

[デバッグ]>[ウィンドウ]>[例外設定] メニュー コマンドを選択すると、ウィンドウが開き、 [Python Exceptions (Python 例外)] を展開することができます。

Exceptions window in the Visual Studio debugger

各例外のチェックボックスは、それが発生したときに 常に デバッガーを中断するかどうかを制御します。 特定の例外で中断する頻度を増やすには、該当するチェックボックスをオンにします。

既定では、ほとんどの例外は、ソース コードに例外ハンドラーが見つからないときに中断します。 この動作を変更するには、例外を右クリックし、 [ユーザー コードで処理されない場合は続行] オプションを変更します。 特定の例外で中断する頻度を減らすには、該当するチェックボックスをオフにします。

この一覧に表示されていない例外を構成するには、 [追加] ボタンを選択して追加します。 この名前は、例外の完全名と一致している必要があります。

プロジェクトのデバッグ オプション

既定では、デバッガーは標準的な Python ランチャーを使用してプログラムを起動します。コマンドライン引数も、特別なパスや条件も使用しません。 スタートアップ オプションはプロジェクトのデバッグ プロパティで変更することができます。デバッグ プロパティにアクセスするには、ソリューション エクスプローラーでプロジェクトを右クリックし、 [プロパティ] を選択して、 [デバッグ] タブを選択します。

Project debug properties in the Visual Studio debugger

起動モードのオプション

オプション 説明
標準的な Python ランチャー CPython、IronPython、および Stackless Python などのバリエーションと互換性のあるポータブル Python で記述されたコードのデバッグに使用します。 純粋な Python コードをデバッグするのに最適です。 このランチャーは、実行中の python.exe プロセスにアタッチする場合に使用されます。 このランチャーには CPython 用の混合モード デバッグも用意されており、C/C++ コードと Python コードとの間でシームレスなステップ実行ができます。
Web ランチャー 起動時に既定のブラウザーを起動し、テンプレートのデバッグを有効にします。 詳細については、Web テンプレートのデバッグに関する記事を参照してください。
Django Web ランチャー Web ランチャーと同じです。旧バージョンと互換性のために記載しています。
IronPython (.NET) ランチャー .NET デバッガーを使用します。IronPython でのみ機能しますが、C# や VB を含む任意の .NET 言語プロジェクト間でステップ実行ができます。 このランチャーは、IronPython をホストしている実行中の .NET プロセスにアタッチする場合に使用されます。

実行オプション (検索パス、スタートアップ引数、環境変数)

オプション 説明
検索パス これらの値は、ソリューション エクスプローラーのプロジェクトの [検索パス] ノードに表示される内容と同じです。 ここで値を変更することもできますが、ソリューション エクスプローラーを使用した方が、フォルダーを参照したり、自動で相対パスに変換したりできるので簡単です。
スクリプトの引数 これらの引数は、スクリプトを起動するコマンドのスクリプト ファイル名の後ろに追加されます。 ここで指定した引数は、スクリプトで、最初の引数は sys.argv[1]、2 番目の引数は sys.argv[2] (その後も同様) として利用できます。
インタプリターの引数 これらの引数は、ランチャーのコマンドラインのスクリプト名の前に追加されます。 警告をコントロールする -W ...、プログラムを少し最適化する -O、バッファーなし IO を使用する -u などがよく使用されます。 IronPython のユーザーは、多くの場合、このフィールドを使用して -X オプションを渡します (-X:Frames-X:MTA など)。
インタープリターのパス 現在の環境に関連付けられているパスをオーバーライドします。 非標準のインタープリターを使用してスクリプトを起動する場合に便利です。
環境変数 複数行のテキスト ボックスで、<NAME>=<VALUE> の形式でエントリを追加します。 この設定は最後に適用されます。既存のグローバル環境変数よりも優先され、 [検索パス] の設定に従って PYTHONPATH が設定された後に適用されるため、これらの変数を手動でオーバーライドするために使用できます。

イミディエイト ウィンドウと対話型ウィンドウ

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

イミディエイト ウィンドウ ( [デバッグ]>[ウィンドウ]>[イミディエイト] ) は、Python 式を即座に評価したり、実行中のプログラム内の変数を検査したり割り当てたりする際に使用します。 詳細については、イミディエイト ウィンドウに関する一般的な記事を参照してください。

Python Debug Interactive ウィンドウ ( [デバッグ]>[ウィンドウ]>[Python Debug Interactive] ) は、より豊富な機能を備えています。コードの記述と実行を含め、対話型 REPL のすべてのデバッグ機能を利用できます。 Python Debug Interactive ウィンドウは、標準的な Python ランチャーを使用して、デバッガー内で開始しているすべてのプロセスに自動的に接続します ( [デバッグ]>[プロセスにアタッチする] でアタッチされたプロセスも含みます)。 ただし、C/C++ の混合モード デバッグを使用している場合、Debug Interactive ウィンドウは使用できません。

Python Debug Interactive window

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 ウィンドウに影響はありません。

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

Visual Studio 2017 バージョン 15.8 以降では、ptvsd バージョン 4.1 以降に基づくデバッガーが使用されます。 Visual Studio 2019 バージョン 16.5 以降では debugpy に基づくデバッガーが使用されます。 これらのバージョンのデバッガーは、Python 2.7 および Python 3.5 以降と互換性があります。 Python 2.6、3.1 から 3.4、または IronPython を使用する場合、Visual Studio に "デバッガーではこの Python 環境はサポートされていません" というエラーが表示されます。

Debugger does not support this Python environment error when using the debugger

このような場合は、(Visual Studio 2017 バージョン 15.7 以前の既定である) 以前のデバッガーを使用する必要があります。 [ツール]>[オプション] メニュー コマンドを選択し、 [Python]>[デバッグ] に移動して、 [レガシ デバッガーを使用] オプションを選びます。

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

ptvsd 3.x をインストールした場合は、"デバッガー パッケージを読み込めませんでした" というエラーが表示されます。

Debugger package could not be loaded error when using the debugger

この場合は、 [レガシ デバッガーを使用します] を選択して [レガシ デバッガーを使用] オプションを設定し、デバッガーを再起動します。

以前の 4.x バージョンの ptvsd をインストールした場合、"デバッガー パッケージが最新ではありません" という警告が表示されます。

Debugger package is outdated warning when using the debugger

重要

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

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

  1. [Python 環境] ウィンドウの [パッケージ] タブに移動します。

  2. 検索ボックスに「ptvsd」と入力し、インストールされている ptvsd のバージョンを確認します。

    Checking the ptvsd version in the Python Environments window

  3. バージョンが 4.1.1a9 より前のもの (Visual Studio にバンドルされていたバージョン) である場合は、パッケージの右側にある [X] を選択して古いバージョンをアンインストールします。 これで、Visual Studio ではバンドルされていたバージョンが使用されます (pip uninstall ptvsd を使用して、PowerShell からアンインストールすることもできます)。

  4. または、トラブルシューティングのセクションに記載されている手順に従って、ptvsd パッケージを最新バージョンに更新できます。

トラブルシューティング

Visual Studio 2019 (バージョン 16.4 以前) の場合は ptvsd をアップグレードする

デバッガーで問題が発生する場合は、まず次のようにデバッガーのバージョンをアップグレードします。

  1. [Python 環境] ウィンドウの [パッケージ] タブに移動します。

  2. 検索ボックスに「ptvsd --upgrade」と入力し、 [次のコマンドを実行する: pip install ptvsd --upgrade] を選択します。 (PowerShell から同じコマンドを使用することもできます)。

    Giving the ptvsd upgrade command in the Python Environments window

    問題が解決しない場合は、PTVS GitHub リポジトリで問題を報告してください。

    Note

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

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

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

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

  1. [ビュー]>[その他のウィンドウ]>[コマンド ウィンドウ] メニュー コマンドを使用して、Visual Studio でコマンド ウィンドウを開きます。

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

    DebugAdapterHost.Logging /On /OutputWindow
    
  3. デバッグを開始し、問題を再現するために必要な手順をすべて実行します。 この期間中、 [デバッグ アダプターのホスト ログ] の下の [出力] ウィンドウにデバッグ ログが表示されます。 次に、そのウィンドウからログをコピーし、GitHub の問題や電子メールなどに貼り付けることができます。

    Debugger logging output in the Output window

  4. Visual Studio が応答しなくなったり、または [出力] ウィンドウにアクセスできなくなったりした場合は、Visual Studio を再起動してコマンド ウィンドウを開き、次のコマンドを入力します。

    DebugAdapterHost.Logging /On
    
  5. デバッグを開始し、もう一度問題を再現します。 これで、デバッガーのログが %temp%\DebugAdapterHostLog.txt に見つかります。

関連項目

Visual Studio のデバッガーについて詳しくは、「Debugging in Visual Studio (Visual Studio でのデバッグ)」を参照してください。