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.
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
When a key is not in the tables below, ask the keyboard instead of guessing. wev prints the keysym for every key you press:
$ wev
[ 14: wl_keyboard] key: serial: 84; time: 9302175; key: 115; state: 1 (pressed)
sym: XF86AudioRaiseVolume (269025043), utf8: ''
The sym: field is the string to pass to awful.key. Press the key you care about, read the name, ignore the rest of the output.
This matters most where the name is not what is printed on the keycap. , reports comma, ; reports semicolon, and Page Up reports Prior.
wev is a Wayland client, so run it from inside your SomeWM session. Install it from your distribution's wev package. On X11 under AwesomeWM the equivalent is xev -event keyboard, whose KeyPress lines end with keycode 123 (keysym 0x1008ff13, XF86AudioRaiseVolume); the name after the comma is the same string.
Modifier Keys
Passed as a Lua table — the first argument to awful.key.
| Name | Common Name | Notes |
|---|---|---|
"Mod4" | Super / Windows / Meta | The key with the Windows logo |
"Super" | alias for "Mod4" | Convenience alias |
"Mod1" | Alt | Left or Right Alt |
"Alt" | alias for "Mod1" | Convenience alias |
"Shift" | Shift | Either Shift key |
"Control" | Ctrl | Either Control key |
"Ctrl" | alias for "Control" | Convenience alias |
"Lock" | Caps Lock / Num Lock | Toggleable lock state |
"Mod2" | Mod2 | Often Num Lock on common layouts |
"Mod3" | Mod3 | Layout-dependent |
"Mod5" | Mod5 | Often AltGr / ISO Level 3 |
"Any" | wildcard | Matches any modifier combination |
Combining Modifiers
{ modkey } -- Mod4 only
{ modkey, "Shift" } -- Mod4 + Shift
{ modkey, "Control" } -- Mod4 + Ctrl
{ "Mod1", "Shift" } -- Alt + Shift
{ modkey, "Mod1" } -- Mod4 + Alt
{ modkey, "Control", "Shift" } -- Mod4 + Ctrl + Shift
{ "Any" } -- match regardless of modifiers
Common Key Names
| Key | Lua 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
| Key | Lua Name |
|---|---|
| Left Arrow | "Left" |
| Right Arrow | "Right" |
| Up Arrow | "Up" |
| Down Arrow | "Down" |
Function Keys
| Key | Lua Name |
|---|---|
| F1 – F12 | "F1" through "F12" |
| F13 – F35 | "F13" through "F35" (available, rarely physical) |
Letters and Numbers
| Key | Lua Name |
|---|---|
| Letters | "a" through "z" (lowercase) |
| Numbers | "0" through "9" |
Punctuation
| Key | Lua 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
| Key | Lua 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
| Key | Lua 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" |
"XF86Mail" | |
| Browser | "XF86WWW" |
Mouse Buttons
| Button | Number |
|---|---|
| Left click | 1 |
| Middle click | 2 |
| Right click | 3 |
| Scroll up | 4 |
| Scroll down | 5 |
| Scroll left | 6 |
| Scroll right | 7 |
| Back | 8 |
| Forward | 9 |
Examples
-- Global keybinding
awful.key({ modkey }, "Return", function()
awful.spawn(terminal)
end, { description = "open terminal", group = "launcher" })
-- Keybinding with multiple modifiers
awful.key({ modkey, "Shift" }, "c", function(c)
c:kill()
end, { description = "close", group = "client" })
-- Media key (no modifier)
awful.key({}, "XF86AudioRaiseVolume", function()
awful.spawn("wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%+")
end, { description = "raise volume", group = "media" })
-- Mouse binding
awful.button({ modkey }, 1, function(c)
c:activate({ context = "mouse_click", action = "mouse_move" })
end)
See Also
- All Keysyms – Full enumeration of every xkbcommon keysym
- Keybindings Tutorial – Learn how to create keybindings
- Default Keybindings – Built-in shortcuts
- awful.key (AwesomeWM docs) – Complete API reference