AutoHotkey v2 Linux Port

This documentation set accompanies the AutoHotkey v2.0.26 Linux port (MonoEven/Autohotkey_Linux). The pages in this site are the official AutoHotkey v2 documentation, adapted for the Linux port. Only AutoHotkey v2 syntax is supported; the AutoHotkey v1 language, the v1-to-v2 migration material, and all Windows-specific behavior are not part of this port.

Language and syntax

• v2 only. The interpreter is built from the AutoHotkey v2.0.26 source. v1 syntax, commands and directives are not supported.
• See Scripting language, Concepts and conventions, and the list of built-in functions for the supported v2 feature set.

Examples in this documentation

These pages mirror the official AutoHotkey v2 documentation, so their examples fall into three groups on Linux:

• Run as-is. Pure-language examples (variables, loops, strings, math, files, objects, RegEx, ...) run unchanged. Windows-style paths like C:\... are treated as plain (oddly named) files on Linux; use Linux paths (/tmp/..., A_Desktop, ~) in your own scripts.
• Platform-adapted. Pages for DllCall and the COM functions (ComObject, ComObjGet, ...) add a Linux example block at the top of their Examples section that uses native .so libraries or the D-Bus bus; the original Windows examples are kept for reference only.
• Not available on Linux. Examples using Windows-only features (GUI windows via Gui/GuiControl/Menu, SoundBeep/SoundPlay, TrayTip, SendMessage/ PostMessage/OnMessage, Hotstring, ...) are kept for reference; calling those functions raises a clear error. Many examples elsewhere are also short snippets that depend on context (a preceding variable, a hotkey label, a window with a specific title); they illustrate syntax rather than being standalone programs.

What works on Linux

All 367 built-in functions listed in the worklist are implemented (3 not-implemented error paths: ComObjArray, TrayTip, TraySetIcon); 1026 doc-check assertions pass under Xvfb (including 29 for DllCall against native .so libraries and 18 for the D-Bus COM layer). The port has two display backends:

• X11 backend (preferred when DISPLAY is set, including XWayland sessions): window management (Win*), controls, hotkeys via XGrabKey/XGrabButton (keyboard and mouse-button/wheel hotkeys), pixel/monitor access, dialogs, ToolTip, ImageSearch and window shapes.
• Native Wayland backend (used when no X display is available): xdg-shell windows, virtual keyboard/pointer input (zwp_virtual_keyboard_v1 / zwlr_virtual_pointer_manager_v1), screen capture via wlr-screencopy. Global hotkeys in Wayland sessions go through the unified input backend (input_backend.h), which selects automatically:
  • GNOME Shell extension backend (GNOME 49, zero-confirmation exclusive hotkeys: 1::/^1::/F12:: grab and suppress the physical key with no per-binding dialog). The companion extension (extension/ in the repo) is a thin D-Bus broker (io.github.autohotkey.GlobalHotkeys1) that registers accelerators through Meta.Display.grab_accelerator() + Main.wm.allowKeybinding() (the whitelist step the portal backend performs via shellDBus) and relays activations back; it never parses AHK, executes commands or forks. Verified on Ubuntu 25.10 + GNOME 49 (E2E: physical 1 fires the hotkey with no confirmation dialog, the key is suppressed from the focused app, exiting the script restores the key, kill -9 releases the grab fail-open, Ctrl+1/F12 and key-repeat work, and a gnome-shell extension reload (disable/enable) is followed by automatic re-registration). Capability scope (v1): exclusive hotkeys only — ~1:: passthrough, remaps, a & b:: and full wildcards are NOT in this backend (evdev/ahk-inputd lane); 1 up:: has its signal source (accelerator-deactivated is relayed) but is not yet consumed by the runtime.
  • XDG Global Shortcuts Portal backend (org.freedesktop.portal.GlobalShortcuts, GNOME 45+/KDE, the standard safe fallback): Hotkey registrations bind with the compositor and fire on the physical key. Caveat: a few compositor/driver builds (e.g. Ubuntu 25.10 ’s xdg-desktop-portal 1.20.3 + GNOME 49) only accept binds when they can resolve a valid app identity for the caller (a bare CLI resolves none and is rejected); run from a matching .desktop/app scope on those systems.
• Backend selection: AHK_INPUT_BACKEND=auto|x11|portal|gnome-shell|evdev (auto: X11 session → X11; GNOME Wayland with the extension installed → gnome-shell; other Wayland → portal; evdev reports “backend not installed” until ahk-inputd ships). AHK_FORCE_GLOBAL_SHORTCUTS=1 keeps its documented meaning: explicitly require the standard Portal backend (it is not reused for the GNOME Shell backend). An XWayland/Xorg session remains the stable fallback on all systems.

Differences from Windows AutoHotkey

• No GUI windows (Gui, GuiControl, Menu objects are not portable and are not implemented); use text-based or external tools.
• COM is implemented over D-Bus: ComObject("service") (or ComObjGet) creates a proxy for a D-Bus service; method calls and property access map to D-Bus method/property calls; ComValue wraps typed values (integers, doubles, strings, booleans, bytes). Windows COM interfaces (IUnknown/IDispatch pointers, SafeArrays, events) do not exist on Linux; ComObjQuery/ComObjConnect/ComObjArray raise an error.
• DllCall is supported for native Linux shared objects (.so): functions are resolved with dlopen/dlsym and called through libffi, with Int/Int64/Short/Char/Float/Double/Ptr/Str/AStr/WStr argument types, by-address (&Var) output parameters, and HRESULT-style error reporting. Windows DLLs are not loadable.
• No registry access (Windows registry), no Win32 messages for other windows.
• The SoundGet*/SoundSet* mixer functions are available via pactl (PipeWire/PulseAudio) with an ALSA amixer fallback; SoundPlay (paplay/aplay) and SoundBeep (terminal/X11 bell) work too. The tray icon (TrayTip) and compiled-script packaging are not available.
• CoordMode/SendMode semantics are honored; hotkeys work through XGrabKey (keys) and XGrabButton (mouse buttons/wheels) on X11/XWayland. LoadPicture decodes BMP/ICO/PNG/GIF/CUR/JPEG/PPM.

See CHECK_REPORT.md for the complete per-module report.

Latest release

The latest official release is v2.0.26-linux.11. Highlights of this release:

• LoadPicture now decodes GIF (first frame; GCT/LCT palettes, GCE transparency, interlace, hand-written LZW), CUR (ICONDIR type 2, DIB shared with ICO) and JPEG (via libjpeg, baseline and progressive) in addition to BMP/ICO/PNG/PPM. Transparency maps to the magenta sentinel like the other formats.
• Mouse hotkeys (XGrabButton): LButton/RButton/MButton/XButton1/ XButton2 and WheelUp/Down/Left/Right, with modifier combinations, key-up variants, and deterministic passthrough for ~/HotIf-false/ Off hotkeys (passive grab removed + XTEST re-injection; the server swallows a press injected while the button is held).
• Doc-check: 1047/1047 assertions pass on both the normal and the ASan builds; regression 27/27, Wayland 13/13, XWayland 247/247.

Build and install

git clone --branch linux-port https://github.com/MonoEven/Autohotkey_Linux.git
cd Autohotkey_Linux
cmake -S . -B build-core
cmake --build build-core -j$(nproc)
build-core/source/linux/core/ahk_core your-script.ahk

Prebuilt packages (tar.gz / .deb) and an installer are published with each GitHub Release: releases.

Version history

This port is based on AutoHotkey v2.0.26. The v1-to-v2 change documentation has been removed because v1 is not supported by this port.

Software License: GNU General Public License