How to Install AutoHotkey (Linux)

This page is for the AutoHotkey v2 Linux port (branch linux-port of MonoEven/Autohotkey_Linux). It provides an X11 backend (also used on XWayland) and a native Wayland backend. On Windows, install the official AutoHotkey from autohotkey.com instead.

Prebuilt packages (recommended)

Every GitHub release publishes four package formats for 64-bit Linux plus the Arch PKGBUILD:

The Arch PKGBUILD (in tools/linux/) builds the same system-wide package for pacman.

Install the .deb, RPM or AppImage

# Debian/Ubuntu (after install: gnome-extensions enable ... once per user)
sudo apt install ./autohotkey-linux-<version>-amd64.deb

# Fedora/openSUSE
sudo dnf install ./autohotkey-linux-<version>-amd64.rpm

# AppImage (portable)
./autohotkey-linux-<version>-amd64.AppImage --install-extension

Install from the tarball

Extract the archive, then run the CLI or GUI installer from the unpacked tree:

tar xzf autohotkey-linux-<version>-amd64.tar.gz
cd autohotkey-linux
./tools/linux/install-gui.sh        # graphical wizard (zenity/yad)
./tools/linux/install.sh --prefix ~/.local --gnome-extension
./tools/linux/install.sh --prefix /usr/local --gnome-extension   # system-wide
sudo ./tools/linux/install.sh --prefix /usr/local --inputd-service --yes

The installer places the ahk launcher, the interpreter (ahk_core), ahk-inputd and the bundled manual; ahk is also symlinked into ~/.local/bin (or /usr/local/bin). The input broker binary is inert unless it is started manually or --inputd-service installs its systemd socket.

Optional native evdev/inputd service

The deb and RPM install ahk-inputd.socket but leave this keyboard-reading capability opt-in; enable it with the command below. The daemon is not running until an authorized client connects. For the generic tarball use the root --inputd-service command above. The socket is /run/ahk-inputd.sock, owned by root:input with mode 0660. Grant access only to trusted automation users:

sudo systemctl enable --now ahk-inputd.socket
sudo usermod -aG input "$USER"
# Log out completely and back in, then:
AHK_INPUT_BACKEND=evdev ahk script.ahk
systemctl status ahk-inputd.socket ahk-inputd.service

Membership in input permits reading physical keyboard devices; the package deliberately does not add users automatically. The daemon exits five seconds after the last client disconnects and releases every grab, while the socket remains active for the next on-demand start. AHK_INPUTD_SOCKET may select an explicitly managed per-user broker. Automatic discovery checks $XDG_RUNTIME_DIR and then /run, never /tmp. AppImage cannot install a host system service.

Once installed, the ahk launcher also provides: ahk --version (shows the release, e.g. v2.0.26-linux.23), ahk --check (integrity / install method / latest release). It also reports the selected input backend, broker socket presence and whether /dev/uinput is writable; these are diagnostics, while SUPPRESS and INJECT remain negotiated per client. ahk --uninstall (clean removal) and ahk --update [VER] (download + reinstall the latest, or a specific release for upgrading/downgrading (e.g. ahk --update 2.0.26-linux.23). Launcher commands use the -- prefix so plain names like update.ahk are always run as scripts. Every release since v2.0.26-linux.15 stays published on the Releases page with a CKSUMS.txt SHA-256 manifest. New release-tag builds also publish Sigstore/GitHub Artifact Attestations; verify a package with gh attestation verify <file> --repo MonoEven/Autohotkey_Linux. OpenPGP is emitted only when a pinned long-term key is configured; otherwise UNSIGNED.txt says so explicitly. Thus ahk --update <VER> can upgrade or downgrade to any published release; fixes and bespoke state can be rolled back. Releases before linux.15 (linux.14 and earlier) were removed when the new installer line shipped — their source remains on the v2.0.26-linux.* git tags for source-level rollback.

What --update / --uninstall do per install method. The launcher detects how the copy was installed and routes the command to the matching tool:

GNOME 49 Wayland zero-confirmation global hotkeys (optional)

On GNOME 49 Wayland, 1::-style global hotkeys can grab the physical key with no confirmation dialog (and even with no modifier) using the bundled GNOME Shell extension. There are two equivalent ways to install it:

# Option A - one-step, right after installing the core
# (copies the extension into place AND enables it):
./tools/linux/install.sh --prefix ~/.local --gnome-extension

# Option B - fully manual (the classic way):
mkdir -p ~/.local/share/gnome-shell/extensions
cp -r /path/to/autohotkey-linux/extension/ahk-global-hotkeys@autohotkey.org \
      ~/.local/share/gnome-shell/extensions/
gnome-extensions enable ahk-global-hotkeys@autohotkey.org

# ... either way: restart GNOME Shell, because a freshly-placed extension
# only loads at start.  Log out and back in, or press Alt+F2 and type 'r'.

…/autohotkey-linux is the unpacked release tarball (the extension/ directory ships inside it) or the source checkout. The interactive CLI installer also asks on a GNOME session; say y to install the extension in the same run. Without --gnome-extension (and outside an interactive GNOME session) the core install never touches the extension — that part stays fully under the user's control.

The extension is a thin D-Bus broker; the interpreter picks the gnome-shell backend automatically on GNOME Wayland (AHK_INPUT_BACKEND=auto, default), or explicitly with AHK_INPUT_BACKEND=gnome-shell. Without the extension, or on other Wayland compositors, hotkeys fall back to the standard Global Shortcuts Portal backend (AHK_FORCE_GLOBAL_SHORTCUTS=1 forces Portal even behind XWayland).

Extension activation / deactivation / deletion — and what core updates never touch. The GNOME Shell extension is a separate, user-scoped component. install.sh, ahk --uninstall and ahk --update only manage the interpreter files under the install prefix; they do not install, enable, disable, overwrite or delete the extension. Concretely:

Because the extension talks to the interpreter over the session D-Bus bus with a stable interface, the extension does not need to be reinstalled when the core is updated; keep the extension version that matches your GNOME Shell (the bundled metadata.json declares Shell 45–50, with a warning logged when the Shell major differs from the verified 49).

Build from source

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

Requirements: a C++17 compiler, CMake ≥ 3.16, X11/XTest development headers and GTK3 for the GUI; on Debian/Ubuntu: ninja-build libx11-dev libxtst-dev libxrandr-dev libxinerama-dev libxext-dev libxi-dev libwayland-dev wayland-protocols libxkbcommon-dev libffi-dev libdbus-1-dev libgtk-3-dev zlib1g-dev libjpeg-dev. The Wayland backend is optional (used when no X display is available).

Next Steps

See Linux port overview for what works and the differences from Windows AutoHotkey, then Using the Program and the Beginner Tutorial (all documentation applies to the port; platform-specific notes are marked).

These tutorials focus on specific common tasks:

Problems?

If you have problems installing AutoHotkey on Linux, search the issue tracker or open a new issue with the version, your distribution and the output of ahk --version.