python -m pdb -p PIDで接続できないときは、接続側がPython 3.14以降か、対象PIDが同じmajor・minor版のCPythonか、OSのデバッグ権限を満たすか、対象がI/O待ちで止まっていないかを順に確認します。Python 3.14で追加されたPIDアタッチは、任意のPythonや任意のプロセスへ無条件に接続できる機能ではありません。
2026年10月4日時点の公式資料では、代表的な失敗要因として、古い接続側Python、誤ったPID、版・ビルド構成の不一致、OS権限、既存tracer、I/O待ち、リモートデバッグの無効化が挙げられます。
症状別に最初の確認先を決める
| 症状 | 最初に確認すること |
|---|---|
-pや--pidが認識されない | 接続側のPythonが3.14以降か |
PermissionErrorなど権限エラー | 対象の所有者、OSのデバッグ権限、既存tracer |
| 実行後に待ち続ける | 対象がシステムコールやI/O待ちか |
| 版不一致に関する失敗 | 接続側と対象のmajor・minor版、pre-release、free-threaded構成 |
| 条件が合うのに利用できない | 環境変数、-X、ビルド設定、対応プラットフォーム |
pdb公式ドキュメントでは、-p／--pidはPython 3.14で追加され、指定したPIDの実行中プロセスへ接続する機能と説明されています。
1. 接続に使うPythonを確認する
python --version
python -c "import sys; print(sys.executable); print(sys.version)"
python -c "import sysconfig; print(sysconfig.get_config_var('Py_GIL_DISABLED'))"仮想環境、pyenv、コンテナ、複数のPythonがある端末では、pythonが想定外の実行ファイルを指していることがあります。対象を起動した環境と同じPython実行ファイルから接続するのが基本です。
対象はCPythonで、接続側と対象側のmajor・minor版が一致する必要があります。どちらかがalpha、beta、release candidateなら完全に同じ版が必要です。さらにfree-threadedのビルド構成も一致させます。条件はsys.remote_execの公式説明とリモートデバッグ接続プロトコルで確認できます。
接続側と対象を起動する環境の両方で確認してください。Py_GIL_DISABLEDが1ならfree-threaded対応ビルドです。これは現在GILが有効かどうかとは別の判定です。free-threaded Pythonの公式確認方法も参照できます。
2. PIDを確認して接続する
PIDはTCPポート番号ではありません。OSのプロセス一覧で、自分が管理する対象CPythonが現在も生存しているかを確認します。自分が管理する検証用のsample.pyなら、起動時に次のようにPIDと対象Pythonを表示できます。
import os
import sys
import sysconfig
import time
print("PID:", os.getpid(), flush=True)
print(sys.executable, flush=True)
print(sys.version, flush=True)
print("Py_GIL_DISABLED:", sysconfig.get_config_var("Py_GIL_DISABLED"), flush=True)
while True:
time.sleep(1)対象に使うPythonでpython sample.pyを実行し、表示されたPIDへ、同じホストの別ターミナルから接続します。次の1234は例なので、実際のPIDに置き換えてください。
python -m pdb -p 1234接続できると(Pdb)プロンプトが表示されます。まずwhereなどで現在のフレームを確認し、式評価や代入が対象プロセスの状態を変え得ることを理解してから操作してください。
3. PermissionErrorならOS権限を確認する
Linuxでは同一ユーザーのプロセスでも、Yamaのptrace制限、コンテナのセキュリティ設定、別のtracerが原因になる場合があります。straceやgdbがすでに接続していると、同時にPIDアタッチできません。読み取り確認として所有者、ptrace_scope、TracerPidを調べ、組織のセキュリティ方針に従ってください。
macOSでは対象プロセスをデバッグ可能にするentitlementなどが関わり、Windowsでは通常、管理者権限が必要で、さらにSeDebugPrivilegeが必要なプロセスもあります。sudo、全体のptrace_scope緩和、コンテナ隔離の無効化を一律の解決法にはできません。権限を広げる前に、管理された開発・検証環境で必要性を確認します。OSごとの条件は公式の権限要件を参照してください。
4. 待機したままならI/O待ちを確認する
公式pdb資料では、対象がシステムコールでブロック中、またはI/O待ちの場合、次のPythonバイトコードを実行するか、シグナルを受けるまで接続が進まないと説明されています。待機だけでPID間違いと断定しないでください。
自分の検証プロセスなら、通常のテスト入力や処理再開によって次の実行機会を作り、接続が進むか確認します。本番プロセスへ任意のシグナルを送ったり、強制停止したりする操作を既定手順にはしません。
5. リモートデバッグが無効化されていないか確認する
- 対象と接続側で
PYTHON_DISABLE_REMOTE_DEBUGが設定されていないか - 対象または接続側が
-X disable_remote_debugで起動していないか - CPythonが
--without-remote-debugでビルドされていないか - 利用中のプラットフォームが機能に対応しているか
コマンドラインと環境変数の公式資料によると、PYTHON_DISABLE_REMOTE_DEBUGは空でない文字列なら無効化します。値が0でも空文字列ではないため無効です。環境変数と-X disable_remote_debugは、他プロセスへ実行を依頼する機能と、このプロセスで受け取る機能の両方を無効にします。ビルド設定の資料では、--without-remote-debugを使うと送受信機能のコード自体がコンパイルされないと説明されています。
よくある質問
Python 3.14のpdbからPython 3.13へ接続できますか？
できません。対象は同じmajor・minor版のCPythonである必要があります。
待機中にシグナルを送ればよいですか？
公式にはシグナル受信でも接続が進むと説明されていますが、任意のシグナルは対象の動作を変える可能性があります。通常の入力で動かせる自分の検証プロセスを除き、安易に実行しないでください。
qで終了すると対象プロセスも止まりますか？
通常のpdbのquitは、公式コマンド説明では実行中のプログラムを中止します。一方、CPython 3.14.8のPIDアタッチ実装には、終了時に接続を閉じ、BdbQuitを発生させずにデタッチする処理があります。通常のpdbとPIDアタッチの終了処理を一緒にせず、利用する版と接続方式を検証用プロセスで確認してください。「qならどのpdbでも対象が必ず残る」と保証する操作にはできません。
まとめ
pdb -pの失敗は、Python 3.14か、正しいPIDか、版とfree-threaded構成が一致するか、OS権限を満たすか、対象がI/O待ちか、無効化設定がないかの順で確認します。対象プロセスの状態を変更できる機能なので、自分が管理する開発・検証環境で慎重に使用してください。
コメント