Unable to attach pdb remote debugger on MacOS

[anze3db]

Bug report

Bug description:

When I try to attach a remote debugger on MacOS with:

python3.14 -m pdb -p 58653

I get the following error:

Traceback (most recent call last):
  File "<frozen runpy>", line 198, in _run_module_as_main
  File "<frozen runpy>", line 88, in _run_code
  File "/Library/Frameworks/Python.framework/Versions/3.14/lib/python3.14/pdb.py", line 3610, in <module>
    pdb.main()
    ~~~~~~~~^^
  File "/Library/Frameworks/Python.framework/Versions/3.14/lib/python3.14/pdb.py", line 3541, in main
    attach(opts.pid, opts.commands)
    ~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/Library/Frameworks/Python.framework/Versions/3.14/lib/python3.14/pdb.py", line 3425, in attach
    sys.remote_exec(pid, connect_script.name)
    ~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
PermissionError: Cannot get task port for PID 58653 (kern_return_t: 5). This typically requires running as root or having the 'com.apple.system-task-ports' entitlement

The same thing happens also with sudo:

sudo python3.14 -m pdb -p 58653

or the root user:

sudo su
sh-3.2# python3.14 -m pdb -p 58653

I am able to get it to work by running the same command on Linux in Docker:

root@40505a05971f:/data# python -m pdb -p 13
> /data/remote_debugging.py(8)<module>()
-> time.sleep(1)

This is on MacOS Sequoia Version 15.5 and I'm using Python 3.14.0rc1 (b4 had the same issue though).

The release notes don't mention anything about this being a Linux only feature so I'm not sure if I'm doing something wrong or if this is an actual bug.

The script that I'm trying to attach to:

import os
import time

print(os.getpid())
counter = 1
while True:
    counter += 1
    time.sleep(1)

CPython versions tested on:

3.14

Operating systems tested on:

macOS

[ronaldoussoren]

I get the same with the python.org installer.

This appears to be related to notarization, likely a missing entitlement.

@ned-deily, com.apple.security.cs.debugger appears to be relevant here.

In particular:

• When I remove notarization and re-add the same entitlements and the hardened runtime option with an ad-hoc signature I get the same error
• -When I do the same, but add com.apple.security.cs.debugger to the entitlements I can debug

That said, the documentation I link above says amongst others:

When a non-root user runs an app with the debugging tool entitlement, the system presents an authorization dialog asking for a system administrator’s credentials. If authorization succeeds, the debugger receives a 10-hour session before authorization expires.

I didn't get this dialog during testing, but that was using an ad-hoc signature. The phrasing is worrisome because it doesn't mention if the dialog is only shown when using the restricted APIs. Getting a scary dialog when using python would be bad.

[gaogaotiantian]

@pablogsal this is a remote_exec permission issue.

[ned-deily]

Thanks for the report, @anze3db. And thanks for the analysis, @ronaldoussoren. I'll experiment with adding the debugger entitlement and report back.

@gaogaotiantian and @pablogsal, these kind of entitlement issues do not generally arise with ad hoc builds of Python and also likely not with some/most other third-party distributors of Python on macOS. They do arise with the python.org macOS installer because of the extra security hoops we have to go through (e.g. code signing, use of the hardened runtime, and code notarization) to be able to distribute Python via a downloadable installer that will meet Apple's Gatekeeper requirements. I'll also look into seeing if we need to document something.

[ronaldoussoren]

It might be worthwhile to add a buildbot that add-hoc signs binaries using the the same settings as used by that installer. That would have caught this issue earlier, likewise for some LLDB debugging issues we had earlier. That said, this would add more complexity to the build with limited pay off.

Documenting this requirement would be nice, the entitlement is also needed for tools like pyinstaller and py2app if they want to generate app bundles that can be debugged using the remote debugger.

[pablogsal]

See also the work here: #134290 .

We can add more information about this in the doc once we settle on something