AutoKey: X11 Desktop Automation for Linux, and What It Cannot Do on Wayland

The problem AutoKey solves, and who actually needs it

Typing the same block of text into a terminal, an editor and a chat window is a manual task with no shell equivalent. AutoKey sits between your keyboard and the focused application and turns a trigger into an action. The trigger is either a hotkey or a short string you type; the action is a stored phrase or a Python script. That is the whole product.

The audience is narrow by design. The README calls AutoKey a desktop automation utility for Linux and X11, and it says the project has been updated to run on Python 3. If you work on a Linux desktop and your repetitive work is keyboard-shaped, this is the tool. If your repetitive work is file-shaped or server-shaped, a shell script or a cron job is a better fit and AutoKey adds nothing. The former Google Code hosting is noted in the README, which is a hint about how long this project has existed and how much of its user base predates the current repository.

How AutoKey intercepts triggers and runs Python scripts

The repository layout tells you the shape of the system. There is a lib/ directory holding the application code, a config/ directory, and two command-line entry points at the top level: autokey-run and autokey-shell. The GUI is built on GTK3 and PyQt5, both listed in the repository topics, so the interface is a desktop application rather than a daemon you configure through files alone.

A phrase is literal text. A script is Python executed inside AutoKey's own runtime, which is why the README distinguishes between an AutoKey error message, an AutoKey traceback and a Python traceback when you file a bug. Those three artifacts come from different layers: the application, its scripting interface, and your code. The distinction matters because a script that raises an exception shows up as a Python traceback inside an AutoKey error message, and the README asks for the traceback rather than a description of what went wrong.

setup.py reads version and author metadata out of lib/autokey/common.py at build time. That is an unusual choice: the version string lives in the source module, not in setup.py, so a downstream packager who patches one and not the other gets a mismatch. It also means setup.py refuses to run if that file is unreadable, and it exits with a message naming the file.

Installing AutoKey and running a first phrase on Linux

The README does not carry install commands. It points at the Installing page in the wiki and says, in bold, to remove previous installations of AutoKey fully before installing. The repository also ships an INSTALL file, apt-requirements.txt and pip-requirements.txt at the top level, and a debian/ directory, so distribution packaging exists in-tree.

What setup.py does enforce is checkable. It requires setuptools and it exits if the interpreter is older than Python 3.8:

python3 --version
pip install setuptools

If setuptools is missing, setup.py prints a message telling you to install it with your package manager as python-setuptools or via pip. If the Python version is too old, it prints the version you are using and exits. Both failures are loud rather than silent, which is the right behaviour for a build script.

The repository also carries a pip-requirements.txt, so the dependency set is declared rather than guessed:

pip install -r pip-requirements.txt

Once the application is installed and running, the workflow is the same regardless of distribution: create a phrase, bind it to a hotkey or an abbreviation, and test it in a text field. The README directs new users to the Features and Example Scripts pages of the wiki for how AutoKey works, and those pages are where the trigger types and script API are actually documented. The README itself does not document rollback, nor does it list the GUI steps for creating a phrase.

Wayland is not a caveat, it is a wall

The README states that AutoKey is an X11 application and, as such, will not function correctly when Wayland is in use instead of Xorg. That sentence is the single most important fact about the project for anyone on a modern Linux desktop, because most major distributions now default to a Wayland session and many users do not know which session they are in.

The failure is not graceful degradation. An application that synthesizes keystrokes and observes them depends on the X11 input model, and Wayland deliberately restricts cross-application input access. So the practical test is not whether AutoKey launches but whether the session is Xorg. If you are on Wayland, AutoKey is the wrong tool and no amount of configuration will change that. The README offers no Wayland workaround, and none should be assumed.

A second limitation is scope. Nothing in the README claims Windows or macOS support; the project is described as a utility for Linux and X11. Anyone arriving from AutoHotkey and looking for a drop-in replacement on another platform will not find one here.

AutoHotkey and the difference between the two automation models

The obvious comparison is AutoHotkey, and the search data around this project shows people making it, since questions like what AutoHotkey is used for surface alongside questions about AutoKey itself. The two tools overlap on hotkeys and text expansion but diverge on everything underneath.

AutoHotkey is a Windows product with its own scripting language. AutoKey is a Linux and X11 product whose script layer is Python. That difference is the whole argument. If you already write Python, AutoKey's scripts are ordinary Python running inside the application, and the README's troubleshooting guidance assumes you can read a traceback. If you do not write Python, the scripting side of AutoKey is a language you have to learn anyway, and a tool whose automation is configured through a GUI rather than a script file may suit you better.

The other difference is platform reach. AutoHotkey does not run on Linux, and AutoKey does not run on Windows. Choosing between them is usually decided by your desktop, not by the feature lists.

Release cadence, packaging and the GPL-3.0 licence

The most recent release listed for this repository is v0.96.0, dated 2022-06-05, preceded by v0.96.0-beta.10 in December 2021 and v0.96.0-beta.9 in August 2021. The last push to the repository was on 2026-09-23, so the codebase has moved since that release even though no newer tag appears in the release list. That gap between tags and commits is worth understanding before you decide what to install: a distribution package will give you the released version, while a source checkout from master will give you whatever has landed since.

The README points at CHANGELOG.rst as the best source for what is new and fixed in each release, and that file is in the repository root. If you need to know whether a specific bug is fixed, the changelog is where to look rather than the release list.

AutoKey is licensed under GNU GPL v3, with a plain text copy in the LICENSE file. For most desktop users this changes nothing. For anyone embedding AutoKey in a product, the copyleft terms apply to distributed derivative works, and the README offers no alternative licensing path. That is a constraint to raise with a lawyer, not something to settle by reading a README.

Editorial conclusion

Adopt AutoKey if you are on Xorg and want Python-level control over hotkeys, text expansion and window actions; the wiki Installing page is the only supported install path, and the README says to remove previous installations fully first. Do not adopt it on a Wayland session, since the README states it will not function correctly there, and do not expect it to work on Windows or macOS. Before committing, confirm your session type, check the CHANGELOG.rst for what the current master carries beyond the 0.96.0 release, and read the Troubleshooting wiki page so you can supply an AutoKey error message, an AutoKey traceback or a Python traceback when filing a bug.

Frequently asked questions

Official sources

1. autokey/autokey on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases