Skip to main content
Version: 2.2 (dev)

Key names

Names you can pass to awful.key and awful.button. For the full enumeration of every keysym SomeWM accepts (~2,629 entries including international and dead keys), see All Keysyms.

Case-insensitive

SomeWM resolves keys via xkb_keysym_from_name() with the case-insensitive flag set. "Return", "return", and "RETURN" all resolve to the same keysym.

Finding a Key's Name​

Run wev inside SomeWM to read keysyms:

$ wev
[ 14: wl_keyboard] key: serial: 84; time: 9302175; key: 115; state: 1 (pressed)
sym: XF86AudioRaiseVolume (269025043), utf8: ''

Pass the sym: value to awful.key.

This matters most where the name is not what is printed on the keycap. , reports comma, ; reports semicolon, and Page Up reports Prior.

Install your distribution’s wev package if the command is missing.

Modifier Keys​

Pass modifiers as the first argument to awful.key.

NameCommon NameNotes
"Mod4"Super / Windows / MetaThe key with the Windows logo
"Mod1"AltLeft or Right Alt
"Shift"ShiftEither Shift key
"Control"CtrlEither Control key
"Ctrl"alias for "Control"Convenience alias
"Lock"Caps LockToggleable lock state
"Mod2"Mod2Often Num Lock on common layouts
"Mod3"Mod3Layout-dependent
"Mod5"Mod5Often AltGr / ISO Level 3
"Any"wildcardMatches any modifier combination

Combining Modifiers​

CombinationModifier table
Super{ "Mod4" }
Super + Shift{ "Mod4", "Shift" }
Super + Ctrl{ "Mod4", "Control" }
Alt + Shift{ "Mod1", "Shift" }
Super + Alt{ "Mod4", "Mod1" }
Super + Ctrl + Shift{ "Mod4", "Control", "Shift" }
Any modifiers{ "Any" }

"Super" and "Alt" are not modifier aliases in 2.1. Use "Mod4" and "Mod1".

Common Key Names​

KeyLua Name
Enter"Return"
Space"space"
Tab"Tab"
Escape"Escape"
Backspace"BackSpace"
Delete"Delete"
Insert"Insert"
Home"Home"
End"End"
Page Up"Prior"
Page Down"Next"
Menu"Menu"
Print Screen"Print"
Pause"Pause"
Caps Lock"Caps_Lock"
Num Lock"Num_Lock"
Scroll Lock"Scroll_Lock"

Arrow Keys​

KeyLua Name
Left Arrow"Left"
Right Arrow"Right"
Up Arrow"Up"
Down Arrow"Down"

Function Keys​

KeyLua Name
F1 – F12"F1" through "F12"
F13 – F35"F13" through "F35" (available, rarely physical)

Letters and Numbers​

KeyLua Name
Letters"a" through "z" (lowercase)
Numbers"0" through "9"

Punctuation​

KeyLua Name
Comma ,"comma"
Period ."period"
Semicolon ;"semicolon"
Colon :"colon"
Apostrophe '"apostrophe"
Quote ""quotedbl"
Grave `"grave"
Tilde ~"asciitilde"
Minus -"minus"
Equal ="equal"
Plus +"plus"
Underscore _"underscore"
Left Bracket ["bracketleft"
Right Bracket ]"bracketright"
Backslash \"backslash"
Slash /"slash"
Question Mark ?"question"
Exclamation !"exclam"
At @"at"
Hash #"numbersign"

Keypad​

KeyLua Name
Keypad 0 – 9"KP_0" through "KP_9"
Keypad Enter"KP_Enter"
Keypad + / - / * / /"KP_Add" / "KP_Subtract" / "KP_Multiply" / "KP_Divide"
Keypad Decimal"KP_Decimal"
Keypad Equal"KP_Equal"

Media Keys​

KeyLua Name
Volume Up"XF86AudioRaiseVolume"
Volume Down"XF86AudioLowerVolume"
Mute"XF86AudioMute"
Mic Mute"XF86AudioMicMute"
Play/Pause"XF86AudioPlay"
Pause"XF86AudioPause"
Stop"XF86AudioStop"
Previous"XF86AudioPrev"
Next"XF86AudioNext"
Brightness Up"XF86MonBrightnessUp"
Brightness Down"XF86MonBrightnessDown"
Keyboard Backlight Up"XF86KbdBrightnessUp"
Keyboard Backlight Down"XF86KbdBrightnessDown"
Search"XF86Search"
Calculator"XF86Calculator"
Mail"XF86Mail"
Browser"XF86WWW"

Mouse Buttons​

ButtonNumber
Left click1
Middle click2
Right click3
Scroll up4
Scroll down5
Scroll left6
Scroll right7
Back8
Forward9

Examples​

Constructing a key object does not register it. Global and client bindings use different registration functions:

local awful = require("awful")

awful.keyboard.append_global_keybindings({
awful.key({ "Mod4" }, "Return", function()
awful.spawn("kitty")
end, { description = "open terminal", group = "launcher" }),
})

client.connect_signal("request::default_keybindings", function()
awful.keyboard.append_client_keybindings({
awful.key({ "Mod4", "Shift" }, "c", function(c)
c:kill()
end, { description = "close", group = "client" }),
})
end)

See keybinding patterns for mouse bindings and media keys.

See Also​