pymacos

A Pythonic interface to macOS. Control your whole Mac from Python: apps, notifications, input, screen, camera, microphone, OCR, media 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="Olá")   # 'Hello'
macos.finder.trash("old.log")                   # moved to the Trash

What's inside

Area	Topics
Apps & Automation	Apps, Browser, Clipboard, Events, Hotkeys, Keyboard, Mouse, Music, Schedule, Shortcuts, Windows
User Interaction	Dialogs, Notifications, Sound, Speech
Files & Documents	Audio Files, Finder, Images, PDF, Spotlight, Video
Intelligence	Language, Vision
Security	Keychain
System & Hardware	Appearance, Audio, Bluetooth, Camera, Network, Power, Screen, System, Volume

Install

pip install pymacos

The package is installed as pymacos and imported as macos.

Requires macOS and Python 3.9+.

Why

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.

Documentation

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

License

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.}

appkit audio-devices audio-editing automation battery bluetooth brightness caffeinate clipboard cocoa ctypes dark-mode dialogs document-scanner duplicate-photos embeddings exif finder heic hotkeys keyboard keychain mac macos microphone mouse music notifications ocr osx pdf pose-estimation qr-code remove-background screenshot shortcuts spotlight system-info text-to-speech video video-editing volume wallpaper webcam window-management

Metadata

Release files for pymacos 1.11.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pymacos 1.11.0
File	Size	Uploaded
pymacos-1.11.0.tar.gz	267.1 kB	Sep 29, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pymacos 1.11.0
File	Interpreter	ABI	Platform	Reset
pymacos-1.11.0-py3-none-any.whl 184.3 kB Sep 29, 2026	Python 3	none	any	Details

Total release size: 451.4 kB

Release files / pymacos-1.11.0.tar.gz

Download URL	pymacos-1.11.0.tar.gz
Size	267.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`6ce0552757ced138e8508f0900c6c712d599a111fffac50621be17d40c6c60ae`
BLAKE2b-256 checksum How to use checksums	`0503dd868d0725256688fd2ca0efcb442851fc17a8e2b7ff1285e87a0158a219`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/JeanExtreme002/pymacos
Publishing commit: github.com/JeanExtreme002/pymacos/tree/d5dbb8fee74788a7b974425372894e6def5ae2ed

Workflow

Publishing configuration: github.com/JeanExtreme002/pymacos/blob/d5dbb8fee74788a7b974425372894e6def5ae2ed/.github/workflows/publish.yml
Publishing logs: github.com/JeanExtreme002/pymacos/actions/runs/36532011313/attempts/1

Artifact

Subject: pymacos-1.11.0.tar.gz
SHA-256 checksum: 6ce0552757ced138e8508f0900c6c712d599a111fffac50621be17d40c6c60ae Verifying attestations

Release files / pymacos-1.11.0-py3-none-any.whl

Download URL	pymacos-1.11.0-py3-none-any.whl
Size	184.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`fa9d188f65af78f43ffc0c3a0cf246e6f2fbc571bbd7066c7ff2eb09313dedd2`
BLAKE2b-256 checksum How to use checksums	`7ea03105d854022a35c4307212836403555d06e44e554f4cd9712f259ca22edb`
Upload date	Sep 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/JeanExtreme002/pymacos
Publishing commit: github.com/JeanExtreme002/pymacos/tree/d5dbb8fee74788a7b974425372894e6def5ae2ed

Workflow

Publishing configuration: github.com/JeanExtreme002/pymacos/blob/d5dbb8fee74788a7b974425372894e6def5ae2ed/.github/workflows/publish.yml
Publishing logs: github.com/JeanExtreme002/pymacos/actions/runs/36532011313/attempts/1

Artifact

Subject: pymacos-1.11.0-py3-none-any.whl
SHA-256 checksum: fa9d188f65af78f43ffc0c3a0cf246e6f2fbc571bbd7066c7ff2eb09313dedd2 Verifying attestations