Swap Escape and Caps Lock on Linux

Linux uses the XKB option caps:swapescape to exchange the two keys: Caps Lock behaves as Escape, and Escape behaves as Caps Lock. How that option is applied depends on whether the desktop session uses X11 or Wayland.

Check the current session type and desktop environment with:

printf 'session=%s desktop=%s\n' "$XDG_SESSION_TYPE" "$XDG_CURRENT_DESKTOP"

Wayland

In a Wayland session, the desktop's compositor controls keyboard input. setxkbmap is an X11 tool, so running it under Wayland may affect only XWayland applications or have no useful effect. Configure the XKB option through the desktop environment or compositor instead.

GNOME Wayland

GNOME is the default desktop on distributions such as Ubuntu and Fedora Workstation. Inspect the current per-user XKB options before changing them:

gsettings get org.gnome.desktop.input-sources xkb-options

If the result is @as [] or [], enable the swap with:

gsettings set org.gnome.desktop.input-sources xkb-options "['caps:swapescape']"

This setting persists for the current user and works in the GNOME Wayland session. The command replaces the complete list of XKB options. If the list already contains an option, keep it and add the swap. For example, preserve compose:ralt like this:

gsettings set org.gnome.desktop.input-sources xkb-options "['compose:ralt', 'caps:swapescape']"

To remove the swap, set the list back to what gsettings get showed before the change. If it had no other options, use:

gsettings set org.gnome.desktop.input-sources xkb-options "[]"

GNOME Tweaks can also expose this setting in its additional keyboard-layout options, but gsettings works without installing that extra application.

KDE Plasma Wayland

Open System Settings and then Keyboard. In current Plasma versions, click Key Bindings in the upper-right corner of the Keyboard page. Expand Caps Lock behavior, select Swap Esc and Caps Lock, and apply the change.

Older Plasma versions put the same setting under Keyboard, Advanced. On those versions, first enable Configure keyboard options, then expand Caps Lock behavior and select the swap. The Key Bindings page in newer Plasma replaces this Advanced tab; it is not the separate Shortcuts page shown in the left sidebar.

Plasma stores the choice for the desktop session and applies it to its XKB keyboard configuration. Use the same panel to undo it.

Sway

Add this block to ~/.config/sway/config:

input type:keyboard {
    xkb_options caps:swapescape
}

Reload the configuration with the normal Sway reload shortcut or:

swaymsg reload

If xkb_options is already present, keep all required options in one comma-separated value, such as compose:ralt,caps:swapescape.

Hyprland

Hyprland 0.55 and newer use Lua configuration. Add the option to ~/.config/hypr/hyprland.lua:

hl.config({
    input = {
        kb_options = "caps:swapescape"
    }
})

Hyprland reloads the configuration when it is saved. It can also be reloaded manually:

hyprctl reload

Combine multiple XKB options in one comma-separated string, such as "compose:ralt,caps:swapescape".

Hyprland 0.54 and older use the legacy ~/.config/hypr/hyprland.conf format instead:

input {
    kb_options = caps:swapescape
}

X11

In an X11 desktop session, apply the swap for the current session with:

setxkbmap -option "caps:swapescape"

This does not normally survive logging out. Run it from the desktop environment's startup applications or an X11 startup file to apply it at each login. The script below contains the same command:

swap versus Caps Lock as another Escape

caps:swapescape exchanges the two keys. If the goal is to make Caps Lock act as an additional Escape key while leaving the original Escape key unchanged, use caps:escape in the appropriate command or desktop setting instead.

swap escape and caps