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.10.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.10.0
File	Size	Uploaded
pymacos-1.10.0.tar.gz	252.2 kB	Sep 29, 2026	Details

Built distribution (wheel)

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

Total release size: 426.3 kB

Release files / pymacos-1.10.0.tar.gz

Download URL	pymacos-1.10.0.tar.gz
Size	252.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`51e5fdcfb807e854f3afc3d4f0ff8275964ef2ae3f15bf6b7daea5d95701d1f1`
BLAKE2b-256 checksum How to use checksums	`bf1ee7b97bd232e2c522747d033dda55a163ac414c932b7e7be7905863a6cfce`
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/5293383d4870918397d68fe840104b3e10977a50

Workflow

Publishing configuration: github.com/JeanExtreme002/pymacos/blob/5293383d4870918397d68fe840104b3e10977a50/.github/workflows/publish.yml
Publishing logs: github.com/JeanExtreme002/pymacos/actions/runs/36529194780/attempts/1

Artifact

Subject: pymacos-1.10.0.tar.gz
SHA-256 checksum: 51e5fdcfb807e854f3afc3d4f0ff8275964ef2ae3f15bf6b7daea5d95701d1f1 Verifying attestations

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

Download URL	pymacos-1.10.0-py3-none-any.whl
Size	174.1 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`22c7813759cec63472fa41336f8309d6cce848256425ed8a978c7f8ca0967fa4`
BLAKE2b-256 checksum How to use checksums	`0d470a14d377364d5d23c720148e5fda1f6b45f13fe0296348cf3ef3ff7c6def`
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/5293383d4870918397d68fe840104b3e10977a50

Workflow

Publishing configuration: github.com/JeanExtreme002/pymacos/blob/5293383d4870918397d68fe840104b3e10977a50/.github/workflows/publish.yml
Publishing logs: github.com/JeanExtreme002/pymacos/actions/runs/36529194780/attempts/1

Artifact

Subject: pymacos-1.10.0-py3-none-any.whl
SHA-256 checksum: 22c7813759cec63472fa41336f8309d6cce848256425ed8a978c7f8ca0967fa4 Verifying attestations