Registry /
type-stubs / pyobjc-framework-libdispatch
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.95 runs
build_error
glibcpy 3.10–3.95 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
dispatch
✓ import dispatch
✗ import libdispatch
The preferred import name for libdispatch bindings is 'dispatch'. While 'libdispatch' still works for backward compatibility, 'dispatch' is the modern and recommended approach.
This quickstart demonstrates the use of `dispatch_once` from the `libdispatch` bindings to ensure a function runs only a single time across application execution. Note the requirement for an `array.array('l', [0])` as the predicate argument for `dispatch_once`.
import array
from dispatch import dispatch_once
# dispatch_once ensures a block of code is executed only once,
# even if called multiple times from different threads.
# It requires an array.array instance as its first argument
# to track whether the block has been run.
predicate = array.array('l', [0]) # Must be a mutable array of long (C 'long')
def my_initialization_function():
print("Performing one-time initialization...")
# Simulate some work
import time
time.sleep(0.1)
print("Initialization complete.")
print("Attempting to call dispatch_once for the first time...")
dispatch_once(predicate, my_initialization_function)
print("Attempting to call dispatch_once for the second time...")
dispatch_once(predicate, my_initialization_function)
print("Program finished.")
Debug
Known issues
breakingPyObjC 12.x (and thus `pyobjc-framework-libdispatch` 12.x) dropped support for Python 3.9. Similarly, PyObjC 11.x dropped support for Python 3.8. The current version of PyObjC and its framework wrappers require Python 3.10 or later.fixEnsure your Python environment is version 3.10 or newer. If you must use an older Python version, install a compatible older PyObjC release.
affects: PyObjC 11.0 and later, `pyobjc-framework-libdispatch` 11.0 and later.
breakingPyObjC 10.3 introduced a change that broke `__init__` methods in Python subclasses of Objective-C classes if they implicitly relied on PyObjC's default `__new__` behavior without defining their own `__new__`. While partially reverted in 10.3.1, classes that implement `__init__` but not `__new__` and rely on PyObjC's `__new__` might still exhibit issues.fixWhen subclassing Objective-C classes in Python, if you define an `__init__` method, it is best practice to also explicitly define a `__new__` method in your Python class, or adhere strictly to the Objective-C `init...` pattern without overriding `__new__`.
affects: PyObjC 10.3, partially mitigated in 10.3.1. Affects `pyobjc-framework-libdispatch` if used in custom Objective-C subclasses.
gotcha`libdispatch` exposes a low-level C API. Incorrect usage of its functions and types through PyObjC can bypass Python's usual error handling, leading to hard crashes or undefined behavior in your application rather than graceful Python exceptions.fixAlways refer to Apple's official `libdispatch` documentation in conjunction with PyObjC's API Notes. Pay close attention to memory management, thread safety, and expected C types for arguments (e.g., pointers, blocks).
affects: All versions.
deprecatedThe primary import for this framework is `import dispatch`. While `import libdispatch` currently functions for backward compatibility, it is considered the older name for the package. Future PyObjC versions may remove support for the `libdispatch` import name.fixUpdate all import statements from `import libdispatch` to `import dispatch` for future compatibility and to align with current best practices.
affects: PyObjC 10.0 and later.
gotchaSeveral `libdispatch` functions, such as `dispatch_retain`, `dispatch_release`, `dispatch_wait`, `dispatch_notify`, `dispatch_cancel`, and `dispatch_testcancel`, are either unavailable or require specific usage patterns (e.g., using object-specific variants). Additionally, the workgroup APIs introduced in macOS 11 are not supported.fixBefore using a `libdispatch` function, consult the 'PyObjC API Notes: dispatch library' documentation to verify its availability and any specific Python binding requirements, such as the `array.array` argument for `dispatch_once`.
affects: All versions.
Upgrade
Version history
12.2.2latest on PyPI · released Aug 11, 2026
Audit
Dependencies
pyobjc-corerequiredThis package provides bindings for a specific macOS framework, requiring the core PyObjC bridge functionality.
PythonrequiredRequires Python 3.10 or later.