Using a Custom Layout
When you press a key, say the A key, a series of steps occurs to turn the key press into an action on your computer:
- The physical switch activates
- The keyboard firmware detects the switch activation and sends a scan code to your computer
- The operating system receives the scan code and passes it to the input subsystem
- The input subsystem’s current input source maps the scan code to a key code and emits an input event
- Applications receive the input event and perform an action (e.g. causing the letter “a” to appear under the cursor)
To use a non-standard keyboard layout, you need to configure custom logic to run at one of these steps.
Keyboard Firmware
Section titled “Keyboard Firmware”Keyboard firmware handles remapping at step 2: it configures the scan codes your keyboard sends to match your layout before your computer is involved. You can plug your keyboard into any computer and your layout will work, with no software configuration required.
Many enthusiast keyboards let you run custom firmware via QMK or ZMK. Some even let you configure a custom layout using an app or website, such as Vial, which supports a wide variety of keyboards, and manufacturer-specific layout editors from ZSA and MoErgo.
If you have a keyboard that supports configuration, refer to your keyboard’s manual. If not, you can find recommendations from community-driven guides:
Both QMK and ZMK maintain lists of supported keyboards; if yours is on either list, it can run a custom layout:
Keyboard Remappers
Section titled “Keyboard Remappers”Firmware customization requires a keyboard that supports it. Keyboard remappers work in software instead: they intercept your keystrokes at step 3, after the operating system receives the scan code but before the input source maps it to a character. Because remapping happens in software, these tools work on any keyboard. Most remappers can also be configured to apply rules to specific keyboards only, leaving others untouched.
Cross-Platform
Section titled “Cross-Platform”Kanata runs on Linux, macOS, and Windows. On any keyboard, it supports advanced features like multiple key layers, tap-hold behavior, and macros (features typically found only in custom keyboard firmware). It is open source with a publicly auditable codebase, and is widely used in the AKL Discord community.
Windows
Section titled “Windows”AutoHotKey is a general-purpose scripting tool for Windows that has been a trusted standard in the Windows automation community for over 20 years. Key remapping is one of its capabilities, making it a flexible option for users who want to combine keyboard customization with other automation.
EPKL (EPiKaL Portable Keyboard Layout) is a Windows keyboard remapper built on AutoHotKey, designed specifically for keyboard layout customization. It runs without installation and comes with a large set of pre-configured layouts. It is maintained by DreymaR, who has been developing ergonomic keyboard modifications for over 20 years and is a well-known figure in the Colemak community. It is the go-to tool for Windows users who want DreymaR’s ergonomic modifications, which are not available as native Windows input sources.
Karabiner-Elements is a keyboard remapper for macOS that has been maintained by the same developer for over 15 years, keeping pace with evolving macOS architecture across major releases. Layouts Wiki provides downloadable Karabiner-Elements configurations for many keyboard layouts.
Limitations
Section titled “Limitations”Some system contexts are off-limits: the login screen and privileged dialogs run in restricted environments that most remapping tools cannot reach. On Windows this includes the login screen and UAC dialog boxes. On macOS, Karabiner-Elements can be configured to apply your layout at the login screen.
Because remapping depends on the extension running, if it crashes, is turned off, or isn’t configured to run on startup, your layout silently stops working: the system falls back to the underlying OS input source, usually QWERTY. This is especially disorienting when it happens at a password prompt.
On Windows, Kanata has two operating modes with different tradeoffs. Its default mode is more stable but doesn’t apply in privileged contexts, while its Interception driver mode can reach privileged dialogs, though with a stability cost: a known issue can disable all keyboards and mice until reboot.
Custom Input Sources
Section titled “Custom Input Sources”Every major operating system has a built-in mechanism for defining custom keyboard layouts. These operate at step 4, replacing the input source that maps scan codes to characters. Because this is a native OS feature, it requires no special permissions and applies everywhere, including the login screen and privileged dialogs.
Windows
Section titled “Windows”On Windows, custom keyboard layouts are created with Microsoft Keyboard Layout Creator (MSKLC).
macOS uses .keylayout files to define custom keyboard layouts. Layouts Wiki provides .keylayout downloads for its layouts. Ukelele is the standard tool for creating and editing them. It provides a graphical interface where you can assign characters to keys, create dead keys, and define multi-character strings. Once created, a layout can be installed by placing the file in ~/Library/Keyboard Layouts and enabling it in System Settings.
On Linux, keyboard layouts are defined using XKB (X Keyboard Extension). Layouts are written as text configuration files. A user-local layout can be placed in ~/.config/xkb/ without administrator access. The Arch Wiki and Ubuntu community wiki both have detailed walkthroughs.
Limitations
Section titled “Limitations”Some software reads scan codes directly, bypassing the input source. Global hotkeys registered this way bind to physical key positions: a key that sends mod+a on a standard layout will still trigger that hotkey even if your layout has moved a elsewhere. Some applications snapshot the active input source at login and register hotkeys based on that, with no awareness of subsequent changes.
Unlike keyboard remappers, custom input sources have no per-device filtering: they apply to all keyboards equally, with no way to configure different behavior for different input devices.
By default, most operating systems track which input source is active per application. Most operating systems let you disable this so a single input source stays active globally.
Choosing an Approach
Section titled “Choosing an Approach”| Keyboard Firmware | Keyboard Remapper | Custom Input Source | |
|---|---|---|---|
| Keyboard support | Supported keyboards only | Any keyboard | Any keyboard |
| Permissions required | None | Elevated | None |
| Active at login screen | Always | Varies | Always |
| Active in privileged dialogs | Always | Varies | Always |
| Per-device filtering | N/A | Yes | No |
| Failure mode | N/A | Falls back to OS input source | N/A |
| Application compatibility | Universal | Universal | Most; some apps bypass the input source |
Common Configurations
Section titled “Common Configurations”One keyboard. If you have a single laptop or a standard external keyboard, a custom input source is the simplest path. It requires no special permissions, works everywhere including the login screen and privileged dialogs, and has no failure mode. Use a keyboard remapper if you also want advanced features like layers or tap-hold.
Standard external keyboard and a built-in keyboard. If your external keyboard has a similar physical layout to your built-in—ANSI, ISO, or JIS; full-size, TKL, 60%, 70%—both keyboards interpret the same input source the same way. A custom input source works fine here. No per-device filtering is needed because neither keyboard requires a different layout configuration from the other.
ErgoMech or split keyboard and a built-in keyboard. A split or column-stagger board with a significantly different physical layout requires firmware configuration regardless: the key positions are too different to use without programming your own key map. In this case, configure your layout in the keyboard’s firmware and use a keyboard remapper configured to pass through that keyboard’s scan codes untouched while remapping your built-in keyboard to your layout. Tools like Kanata support per-device rules for exactly this setup.
A custom input source is not a good fit here. It applies to all keyboards equally, so when your ergo board is plugged in, you need a standard input source active to avoid double-remapping: sending scan codes that have already been remapped by firmware through a second remapping layer produces garbage output. But that same standard input source breaks your layout on the built-in keyboard. The last input source active before you lock or shut down is the one that applies at the login screen, so close your laptop, unplug the ergo board, take it somewhere else, open it up—and your password doesn’t work, because the input source that was correct for the external keyboard is wrong for the built-in keys.