# xah-fly-keys binds Emacs by how often you use each command

> xah-fly-keys is a modal Emacs keybinding written in Emacs Lisp whose layout is built from command frequency and ergonomics, with layouts for QWERTY, Colemak, Dvorak and a dozen others, all in a single .el file you drop into your load path. It is one person's design, argued on its own terms, and the ergonomics are the argument.

**xahlee/xah-fly-keys** — the most efficient keybinding for emacs

- Repository: https://github.com/xahlee/xah-fly-keys
- Website: http://xahlee.info/emacs/misc/xah-fly-keys.html
- Stars: 536 · Forks: 90
- Language: Emacs Lisp
- License: not declared
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/xahlee-xah-fly-keys

## A keybinding designed from command frequency

xah-fly-keys is described as a modal keybinding for Emacs, like Vim, but based on command frequency and ergonomics. That is the whole thesis, and it is unusual enough to be worth unpacking. A modal scheme such as Vim's assigns a letter to a verb and then a letter to an object, so the two-key sequences are mnemonic and learnable but not frequent-first. This scheme instead starts from which commands a person actually runs and places the common ones on the easiest keys, which is why the README describes the design as based on command frequency and ergonomics rather than on any particular editing philosophy. The layout is also pluggable. The init snippet calls a function to select a layout, and the file lists other popular values including adnw and neo2 for German, azerty and azerty-be, bepo, colemak and colemak-dh, dvorak, norman, programer-dvorak, pt-nativo and qwerty-abnt for Brazilian, qwerty-no and qwerty-se, qwertz, russian, workman, and more.

## The install is one file and one require

Installation is manual by design. You put the file xah-fly-keys.el in ~/.emacs.d/lisp/, creating the directory if it does not exist, and then add a few lines to your Emacs init file:

```elisp
(add-to-list 'load-path "~/.emacs.d/lisp/")

(require 'xah-fly-keys)

;; specify a layout
(xah-fly-keys-set-layout "qwerty")

(xah-fly-keys 1)
```

The two calls at the end are the interesting part. xah-fly-keys-set-layout picks which key arrangement to use, and the argument passed to xah-fly-keys is a number, with 1 shown in the example. The package exposes a single entry point with a numeric argument rather than a set of named options, which tells you something about how it is meant to be used: you set it once in your init file and then live with it. There is no package system entry, no dependency list and no build step, because the repository contains exactly three things, a .gitignore, a README and the xah-fly-keys.el file itself.

## The predecessor idea: ergoemacs-mode

The lineage matters for judging what this project is. The author says the work has been going on since 2013, and since 2007 on ergoemacs-mode, which is the same author's earlier effort. Ergoemacs-mode was not a modal keymap at all; it was a set of ergonomic changes to how Emacs behaves by default, altering individual commands so that common operations take fewer keystrokes. The step from there to xah-fly-keys is the step from patching behaviours to replacing the input layer. That history explains two things about the current design. It explains why the key placement is argued from ergonomics rather than from any editing doctrine, and it explains why the project has stayed small and single-file for so long, since the author has spent a long time on exactly this problem and has not needed a large codebase to express it. It also tells you the audience, which is people who already think about key placement as an ergonomic problem rather than as a matter of muscle memory, and who will therefore be receptive to an argument about which commands deserve the good keys.

## The key engine was rewritten, and the diagram is dated

The README carries a dated news entry, 2020-04-18, announcing a major key engine rewrite by Dan Langlois and Will Dey, with links to their GitHub accounts. That is the most recent dated engineering note in the file, and it says something about how the project is maintained: the key engine was rebuilt by other people, which suggests the design is well enough specified that a rewrite is possible. The repository also carries a key diagram for the QWERTY layout, and the image filename records the date it was generated, 2026-02-15, which is considerably more recent than the 2020 news entry. So the picture is current even though the prose is not, and for a keybinding the diagram is arguably the more useful of the two, since it is what you keep open while you are learning where the keys went.

## What the project is and what it is not

It helps to be clear about the scope of what you are installing. The repository holds a single Emacs Lisp file, not a package with a build system, a test suite or a release process, and it publishes no GitHub releases, so there is no version to pin beyond a commit. The full documentation lives off the repository, on the project home page at xahlee.info/emacs/misc/xah-fly-keys.html, and the README points there for the manual. The top level contains a .gitignore, a README, an i/ directory holding the key diagram image, and the xah-fly-keys.el file itself. There is no package keyword, no dependency list and no test runner, which is a fair description of a personal keybinding project rather than a criticism of it, but it does mean the artifact you install is something you read yourself.

## Where xah-fly-keys is the wrong choice

Three cases. The first is a Vim user who expects the same semantics, because the modal idea is shared but the bindings are not, and the premise here is that keys are ranked by frequency rather than by mnemonic role, so habits carried over from Vim will be wrong often enough to slow you down before the new scheme pays off. The second is anyone who wants to configure the keymap declaratively, because a single Lisp file with a numeric argument is the opposite of a configuration layer, and the trade is that you get a coherent designed scheme instead of a tweakable one. The third is a team that needs a maintained, packaged dependency, since the distribution is a copied file with no releases and the licence is recorded as unknown, which is a fact worth resolving before you vendor it into a shared configuration. Against a stock Emacs keybinding, the difference in approach is that this one removes the multi-key chord sequences that make stock Emacs slow, and the cost is that a modal system is a real learning curve in a way that the stock bindings are not, so the efficiency claim only pays out after the learning.

## Conclusion

xah-fly-keys is a good fit for an Emacs user who has already decided they want a modal editing system and wants the keys arranged by how often the commands are actually used, particularly someone on a non-QWERTY layout who has never been offered a keybinding designed with their layout in mind. It is a poor fit for a Vim user expecting familiar modal conventions, for anyone who wants a keybinding that is configured through a declarative layer, since the whole thing is one Lisp file you read, and for a team that needs an actively maintained package. Check three things before you switch your editing muscle memory over: that the layout you type on is one of the listed values, that you are willing to learn an unfamiliar set of keys rather than mapping the ones you already know, and that the single .el file is acceptable to you as an install method, since the documented path is copying it into ~/.emacs.d/lisp/ and adding a require to your init file.

## FAQ

### What is xah-fly-keys?

It is a modal keybinding for Emacs, like Vim, but based on command frequency and ergonomics rather than on mnemonic two-key sequences. The README describes it as the most efficient editing system in the universe, which is the author's own claim, and the design rationale is that the most frequently used commands get the easiest keys.

### How do I install xah-fly-keys?

Put the file xah-fly-keys.el in ~/.emacs.d/lisp/, creating the directory if it does not exist, then add it to your load path in the init file with add-to-list, require xah-fly-keys, call xah-fly-keys-set-layout with your layout such as "qwerty", and call xah-fly-keys with 1.

### Which keyboard layouts does xah-fly-keys support?

The init file lists qwerty along with adnw and neo2 for German, azerty and azerty-be, bepo, colemak and colemak-dh, dvorak, norman, programer-dvorak, pt-nativo and qwerty-abnt for Brazilian, qwerty-no and qwerty-se, qwertz, russian, workman, and more.

### Where is the full documentation for xah-fly-keys?

Off the repository, at the project home page http://xahlee.info/emacs/misc/xah-fly-keys.html, which the README points to for the full documentation. The repository itself contains only a .gitignore, a README and the xah-fly-keys.el file, and publishes no GitHub releases.

## Sources

- [Issues](https://github.com/xahlee/xah-fly-keys/issues)
- [Project website](http://xahlee.info/emacs/misc/xah-fly-keys.html)
- [README](https://github.com/xahlee/xah-fly-keys/blob/master/README.md)
- [xahlee/xah-fly-keys on GitHub](https://github.com/xahlee/xah-fly-keys)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/xahlee-xah-fly-keys