The parser, compiler and general runtime operate on Windows, Linux and macOS. Features which integrate with windows, input devices, the screen, desktop services or native APIs can require platform-specific backends or permissions.
Windows has the broadest AutoHotkey v2 compatibility.
GUI controls can differ in default size, Z-order and label rendering, and a GUI can appear blank before it has first been shown.
Registry functions and native COM pointers are available only on Windows. ComObject uses Windows COM, D-Bus on Linux, or Apple Events on macOS. The Apple Events backend remains unverified.
On Ubuntu 24.04, Ubuntu 26.04, and derivatives using those bases, including Pop!_OS 24.04, prefer the Launchpad PPA for installation and updates. Debian, Pop!_OS 22.04, and other supported distributions use the release installer. Both routes can install Keysharp and two independent native components. keysharp-input provides keyboard and mouse hooks, synthesis, blocking and idle queries through evdev/uinput. keysharp-desktop provides window automation, capture, cursor queries and movement, monitor geometry and keyboard-map queries. These components serve both X11 and Wayland; operations also depend on the active desktop backend.
sudo apt install software-properties-common sudo add-apt-repository ppa:descolada/keysharp sudo apt update sudo apt install keysharp
Both native components require ABI 1.0 or a compatible newer 1.x minor, with libkeysharp_input.so.1 and libkeysharp_desktop.so.1. Upgrade older 0.x components before using this release.
Keysharp can run without these components, but their operations are unavailable. Input device access requires an active local logind session on seat0. Keyboard and relative-pointer hooks do not provide a complete touchpad gesture interface.
| Desktop backend | Window and capture support | Requirements and limits |
|---|---|---|
| X11 | Window queries and control, push window events, area and window capture, cursor and keyboard-map queries. | Uses the X server through keysharp-desktop. Window operations and capture require the same broker consent as on Wayland. |
| Wayland — GNOME | Window queries and control, push window events, area and window capture, cursor queries and movement, and Taskbar badge/progress integration with the stock overview dash. | Requires the keysharp-desktop GNOME Shell extension. Enabling it may require a logout. |
| Wayland — Cinnamon | Window queries and control, push window events, area and window capture, cursor queries and movement, and Taskbar badge/progress integration with the grouped-window-list. | Requires the keysharp-desktop Cinnamon extension. Area capture requires the compositor's stage capture API. There is no shell Eval fallback. |
| Wayland — KWin/KDE Plasma | Window queries and control, area and window capture, cursor queries, and native Plasma Taskbar badge/progress integration. | Uses the keysharp-desktop KWin integration. Window events use polling. Available capture and control operations depend on the running KWin session. |
| Other Wayland compositors Sway, Hyprland, COSMIC, Wayfire, labwc and others |
Protocol-dependent window listing, state, activation, cursor operations and capture. | Foreign-toplevel protocols do not all supply geometry, state or process IDs. Hyprland adds geometry, process IDs, move/resize and push window events through its IPC. Other foreign-toplevel backends may omit these operations. Portal capture requires a screenshot that can be mapped to the desktop coordinates; unsupported layouts or capture modes remain unavailable. |
Run keysharp-desktop probe as your graphical user to inspect the active backend. The desktop component's support table describes the individual operations.
System installations use polkit to approve permanent scopes for an executable. RequestCapabilities and #Requires capability can request the required scopes together; input and desktop scopes may need separate prompts. Once granted, a scope is reused until revoked. The system components share the InputControl grant. Cursor position, work area, keyboard-map and idle queries do not request an interactive grant.
Consent belongs to the executable hosting the script, so scripts run by the same interpreter share its grants. Root-protected executables retain grants when updated at the same protected path; changed contents of a user-writable executable get a new identity. Loaded scripts and libraries are not separate permission identities. See application identity for the limits of this model.
A user-owned desktop authority is also available. Its consent records can be modified by programs running as that user and do not authorize the system input service. See installing without root.
Controls created by the script support toolkit-based control functions, including ControlSend and ControlSendText. Those functions raise an UnsupportedError for another program's window or control on X11 and Wayland. X11 also exposes native child windows, title and focus operations through the desktop component, but it does not expose the full Windows control model.
For cross-process inspection and automation, use AtSpi.ks. Running it directly opens AtSpiViewer; the library also provides APIs similar to Windows accessibility and UI Automation libraries.
ComObject addresses a D-Bus service, which fills the role COM automation fills on Windows: a named service exposes objects whose methods, properties and signals a script calls by name.
A target is written [session:|system:]service.name[:/object/path]. The session bus is used unless system: is given. When the object path is omitted it is derived from the service name by replacing each dot with a slash; if no such object exists, the error names the objects the service does expose.
Members are resolved through D-Bus introspection, so a service must be introspectable. See ComObject and ComObjQuery for selecting an interface, and ComValue for values whose D-Bus type cannot be derived.
Note: ComCall, ObjAddRef, ObjRelease, ComObjValue, ComObjFlags and ComObjFromPtr throw an error. ComObjArray does not exist on Linux, so referring to it is a compile-time error.
macOS support requires macOS 15 or later. Native input, screen and foreign-window features can prompt for privacy permissions.
| Feature | Availability | Limitation |
|---|---|---|
| Hotkeys and hotstrings | Available | #/Win maps to Command and !/Alt maps to Option. |
| Cursor confinement | Partial | ClipCursor suppresses out-of-bounds movement. |
| GUI windows | Available | Some controls differ from Windows. |
| Window management | Partial | Monitoring also requires Screen Recording. |
| COM APIs | Unverified | ComObject addresses Apple Events. The backend is implemented but has not been verified on macOS hardware. See Interprocess automation with ComObject. |
ComObject addresses a scriptable application through Apple Events, which fills the role COM automation fills on Windows: an application publishes a scripting dictionary whose commands, properties and elements a script uses by name.
Members are resolved through the application's scripting definition, whose terms contain spaces. Spaces and underscores are folded away and case is ignored, so a term such as file name is reachable as FileName, filename or file_name. See ComObject for targets, suite selection, commands and values, and Permissions for the Automation permission.
Note: ComCall, ObjAddRef, ObjRelease, ComObjValue, ComObjFlags and ComObjFromPtr throw an error. ComObjArray does not exist on macOS, so referring to it is a compile-time error.
| Permission | Required for | Capability name |
|---|---|---|
| Input Monitoring | Hotkeys, hotstrings and reading keyboard or mouse input. | InputMonitoring |
| Accessibility | Sending or suppressing input, and controlling or querying other application windows. | InputControl, WindowMonitoring or WindowControl, according to the operation. |
| Screen Recording | PixelGetColor, ImageSearch and Image capture; foreign window-title inventory. | ScreenCapture or WindowMonitoring, according to the operation. |
| Automation | Controlling another application with ComObject. Granted separately for each application controlled. | Requested when the first Apple event is sent. |
Permissions are requested automatically when first needed. A script can request them before hotkeys are registered with #Requires capability, or query/request them at runtime with RequestCapabilities.
#Requires capability InputMonitoring, ScreenCapture
Grant requested permissions in System Settings → Privacy & Security. The runtime waits up to 60 seconds for a grant, but the script usually needs to be restarted after a permission is first enabled.
Installing Keysharp, Using Keysharp, Changes from AutoHotkey to Keysharp