appscript

1.4.0 verified Fri May 01 auth: no python

appscript is a Python library that allows you to control AppleScriptable applications from Python, providing an object-oriented API to bridge Python and AppleScript (via the Apple Event Manager). The current version is 1.4.0, which was released in 2015 and has been in maintenance mode since macOS 10.15 (Catalina) due to significant changes in macOS's Apple Event architecture.

pip install appscript

Common errors

error AttributeError: module 'appscript' has no attribute 'app' ↓

cause Importing the top-level module instead of the specific submodule.

fix

Use 'from appscript import app' instead of 'import appscript'.

error appscript.reference.CommandError: ... (-10004) ↓

cause This error (-10004) indicates a timeout or failure to communicate with the target application. Often due to permissions or app not running.

fix

Ensure the target application is running and that Python (or your script) has been granted automation permissions under System Preferences > Security & Privacy > Automation.

error ModuleNotFoundError: No module named 'appscript' ↓

cause The appscript package is not installed or not in the current Python environment.

fix

Install with 'pip install appscript'. Note that appscript is only available on macOS.

Warnings

gotcha appscript is heavily dependent on Apple's Open Scripting Architecture (OSA). Starting with macOS 10.15 (Catalina), Apple introduced stricter sandboxing and deprecated the use of inter-process Apple Events for non-sandboxed apps. As a result, many scripts may fail or require explicit user permissions via System Preferences > Security & Privacy > Automation. ↓

fix Ensure your application is granted automation permissions in System Preferences. For headless or script use, consider using osascript or PyObjC alternative.

gotcha appscript is not compatible with macOS Big Sur (11.0) and later on Apple Silicon (M1/M2) when running Python under Rosetta 2. Python must be native (arm64) or the library may crash or behave unpredictably. ↓

fix Use a native arm64 Python interpreter (e.g., from python.org or Homebrew). Check with 'python -c "import platform; print(platform.machine())"'.

deprecated The appscript project is effectively in maintenance mode. The last release was in 2015, and there are known issues with modern macOS versions. No future updates are expected. ↓

fix Consider migrating to PyObjC's ScriptingBridge or using osascript via subprocess for new projects.

Imports

app
wrong
```
import appscript
```
correct
```
from appscript import app
```
app is the main entry point; importing the module directly does not give you the app function.
k
wrong
```
from appscript import key as k
```
correct
```
from appscript import k
```
k is a constant for keyword parameters; it is not named 'key'.

Quickstart

Control the Finder to list files on the desktop.

from appscript import app, k

# Get the current Finder
finder = app('Finder')

# List files on desktop
for item in finder.desktop.files():
    print(item.name())