JeanExtreme002/pymacos

Control your whole Mac from Python: apps, notifications, input, screen, camera, microphone, OCR, media, Keychain, Touch ID and more, with one import and zero dependencies.

docs
tests
package

import macos

macos.notify("Build finished", title="CI")
macos.say("Done!")

macos.clipboard.copy("hello")
macos.appearance.is_dark()                      # True
macos.screenshot("screen.png")

macos.apps.open("Safari")                       # App(name='Safari', ...)
macos.keychain.get("my-app", "alice")           # 's3cret'

macos.power.battery()                           # Battery(percent=87, charging=True, ...)
macos.shortcuts.run("Translate", input="Hola")  # 'Hello'
macos.finder.trash("old.log")                   # moved to the Trash

pip install pymacos

The package is installed as pymacos and imported as macos.

Requires macOS and Python 3.9+.

A notification from plain Python means AppleScript inside a string, which breaks as soon as the message contains a quote:

subprocess.run(["osascript", "-e", 'display notification "Build finished" with title "CI"'])

With pymacos:

macos.notify("Build finished", title="CI")

Across the whole package:

• No dependencies: no PyObjC, nothing to compile.
• Plain, typed functions that return Python objects.
• Any text is safe: nothing is pasted into shell or AppleScript source.
• Clear errors when macOS is missing a permission, instead of silent failures.

See Why pymacos? for a longer comparison.

The full guide and API reference are at macos.readthedocs.io.

Released under the MIT License — free for personal and commercial use.

_{Not affiliated with or endorsed by Apple Inc. macOS is a trademark of Apple Inc.}