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, Clipboard, Hotkeys, Keyboard, Mouse, Music, 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.9.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.9.0
File	Size	Uploaded
pymacos-1.9.0.tar.gz	226.3 kB	Sep 29, 2026	Details

Built distribution (wheel)

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

Total release size: 385.6 kB

Release files / pymacos-1.9.0.tar.gz

Download URL	pymacos-1.9.0.tar.gz
Size	226.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`383e6893929f2cedf22d652aa48d8a8ada325ee3e0b3b8138b1f9653faedd6ea`
BLAKE2b-256 checksum How to use checksums	`97b79ad3c78b605516905d0cbbcb2b4644bb0db0ff7d618d04be644241bacdcd`
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/df54aa984fb9e86631bc15eed9d81e2ae3d0b5a7

Workflow

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

Artifact

Subject: pymacos-1.9.0.tar.gz
SHA-256 checksum: 383e6893929f2cedf22d652aa48d8a8ada325ee3e0b3b8138b1f9653faedd6ea Verifying attestations

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

Download URL	pymacos-1.9.0-py3-none-any.whl
Size	159.3 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`4c6ac5f02ed937efa62372fceb656afc7ee3c3cb90453f503b4e4d94ab5acf73`
BLAKE2b-256 checksum How to use checksums	`4defb417cd36b1d0a79210d72a012960c1888d06c1646d589e1f3f4a02bf707c`
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/df54aa984fb9e86631bc15eed9d81e2ae3d0b5a7

Workflow

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

Artifact

Subject: pymacos-1.9.0-py3-none-any.whl
SHA-256 checksum: 4c6ac5f02ed937efa62372fceb656afc7ee3c3cb90453f503b4e4d94ab5acf73 Verifying attestations