quickmachotkey 2025.7.28

Bind a global hotkey, on macOS, in Python

This is a set of minimal Python bindings for the undocumented macOS framework APIs that even the most modern, sandboxing-friendly shortcut-binding frameworks use under the hood for actually binding global hotkeys.

Unlike something full-featured like MASShortcut, this provides no configuration UI; you have to provide keyboard constants directly.

Simple example:

from quickmachotkey import quickHotKey, mask
from quickmachotkey.constants import kVK_ANSI_X, cmdKey, controlKey, optionKey

@quickHotKey(virtualKey=kVK_ANSI_X, modifierMask=mask(cmdKey, controlKey, optionKey))
def handler() -> None:
    print("handled ⌘⌃⌥X")

if __name__ == "__main__":
    from AppKit import NSApplication  # type:ignore[import]
    from PyObjCTools import AppHelper  # type:ignore[import]
    print("type ⌘⌃⌥X with any application focused")
    NSApplication.sharedApplication()
    AppHelper.runEventLoop()