Registry /
communication / pyobjc-framework-scriptingbridge
Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
build_error
glibcpy 3.10–3.940 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
SBApplication
✓ from ScriptingBridge import SBApplication
ScriptingBridge classes are typically imported directly from the `ScriptingBridge` module.
This quickstart demonstrates how to use `ScriptingBridge` to interact with the Music app (or iTunes on older macOS) to check if it's running and retrieve the name of the currently playing track. It showcases `SBApplication` for referencing scriptable applications by their bundle identifier.
from ScriptingBridge import SBApplication
from AppKit import NSWorkspace # NSWorkspace can be used to check if an app is running
def get_itunes_track_name():
# Get a reference to iTunes (or Music app on newer macOS)
try:
itunes = SBApplication.applicationWithBundleIdentifier_("com.apple.itunes")
except Exception:
# On macOS Catalina and later, iTunes was replaced by the Music app.
# ScriptingBridge might still reference 'itunes', but bundle ID changed.
itunes = SBApplication.applicationWithBundleIdentifier_("com.apple.Music")
if itunes and itunes.isRunning():
current_track = itunes.currentTrack()
if current_track:
return f"iTunes/Music is playing: {current_track.name()}"
else:
return "iTunes/Music is running, but no track is playing."
else:
return "iTunes/Music is not running."
if __name__ == "__main__":
print(get_itunes_track_name())
Debug
Known issues
breakingPyObjC versions frequently drop support for older Python versions. PyObjC 12.0 dropped Python 3.9 support, and 11.0 dropped Python 3.8. Ensure your Python environment meets the `requires_python` spec (currently `>=3.10` for v12.1).fixUpgrade your Python environment to 3.10 or newer, or pin your `pyobjc` dependency to an older version that supports your Python version.
affects: >=11.0
breakingPyObjC 11.1 aligned the core bridge's behavior with `clang`'s documentation for Automatic Reference Counting (ARC) regarding initializer methods. Methods in the 'init' family now correctly steal a reference to self and return a new reference, which can subtly change object lifecycle and memory management in Python code that directly interacts with Objective-C initializers.fixReview code that directly calls Objective-C `init` family methods (e.g., `alloc().init()`) or custom Objective-C classes exposed to Python. Ensure proper reference handling and avoid premature deallocation.
affects: >=11.1
gotchaPyObjC 11.0 introduced *experimental* support for free-threading (PEP 703) with Python 3.13. While promising, this is an experimental feature and might have stability or performance implications that are not fully mature. Use with caution in production environments.fixWhen using Python 3.13 with `pyobjc` in a free-threaded build, thoroughly test your application for stability and correctness. Report any issues to the PyObjC project. For critical applications, consider sticking to non-free-threaded Python builds until the feature is stable.
affects: >=11.0 (Python 3.13+)
gotchaThe behavior of `__init__` when a Python class (or its superclass) implements `__new__` was changed in PyObjC 10.3 (disallowing `__init__`) and then partially reverted in 10.3.1 to reintroduce `__init__` support under those conditions. This can affect how you define Objective-C proxy classes in Python.fixIf you define Python subclasses of Objective-C objects that implement `__new__`, ensure your `__init__` methods are correctly called and behave as expected, especially if migrating from versions prior to 10.3. Test class instantiation thoroughly.
affects: 10.3, >=10.3.1
gotchaPyObjC 12.1 automatically disables Key-Value Observing (KVO) usage for subclasses of `NSProxy` defined in Python. If your application relies on KVO for custom `NSProxy` subclasses, their behavior might change unexpectedly.fixIf you have Python-defined `NSProxy` subclasses that were implicitly using KVO, you may need to re-evaluate their design or implement manual observation mechanisms, as automatic KVO is now disabled for them.
affects: >=12.1
Upgrade
Version history
12.2latest on PyPI · released May 30, 2026
Audit
Dependencies
pyobjc-corerequiredThis package provides the core bridge between Python and Objective-C. All `pyobjc-framework-*` packages depend on it implicitly.