ICEWM-KEYS(5)

📦
version 4.1.0 · 17 versions
, in arch rolling

💅 ICEWM-KEYS(5) — the keys file, explained by your favorite unix bestie

okay so this is icewm-keys, aka the icewm keys configuration file, and it lives in section 5 of the manual (Standards, Environments and Macros, fancy i know 🎀). it's literally just the file where you tell icewm which hotkeys launch which apps. no cap, it's the most fun config file in the whole WM.

✨ NAME ✨

icewm-keys — the icewm keys configuration file. that's it, that's the name, and yes she's iconic 💅

🌸 SYNOPSIS 🌸

$ICEWM_PRIVCFG/keys
$XDG_CONFIG_HOME/icewm/keys
$HOME/.icewm/keys
/usr/etc/icewm/keys
/usr/share/icewm/keys

these are the spots icewm goes looking for your keys file, in exactly that order 🫶

🦋 DESCRIPTION 🦋

the keys file is where you define global keybindings to launch applications. so like, press a thing → an app appears. main character energy.

a keybinding has three parts, bestie:

  1. the word key
  2. a double-quoted string with an X11 key combination
  3. a program, plus its arguments

these get separated by one or more spaces. empty lines are allowed (live your truth, add blank lines). comment lines start with a hash #.

for example, this right here defines a hotkey to restart icewm:

key "Ctrl+Shift+r"      icesh restart

now — go look at the output of xmodmap -pk for a list of the many keystroke names you can use in icewm key definitions. it's giving encyclopedia, but it's worth it.

since IceWM version 3.4.0, bindings can not only be defined by their keystroke name, but also by their key label. on top of that, the shifted key is now definable as well ✨. so for example, the key with + and = can be bound in either of the following four ways, and all four are identical:

key "Ctrl+Shift+equal"  xterm
key "Ctrl+Shift+="      xterm
key "Ctrl+plus"         xterm
key "Ctrl++"            xterm

to bind the mouse 🖱️, use Pointer_Button1 for button 1, and so on. this only works when the mouse is over the root window. see below for examples, i got you.

sometimes you may want to start an application just once — like, girl, don't open seventeen of them. for this, use the runonce keyword, which accepts an additional resource argument.

the command icesh keys instructs icewm to reload this file. very slay, very convenient, use it after every edit bestie.

🔥 FORMAT 🔥

the syntax of the keys file is as follows:

key "key_combination" program options

where:

  • key — the word key begins the definition of a keybinding. literally the opening line of the whole thing.
  • key_combination — a combination of modifiers and a key, like "Ctrl+Alt+Delete". valid modifiers are Alt, AltGr, Ctrl, Hyper, Meta, Shift, Super. each modifier must be followed by a single plus-sign. the key is either a keystroke name or a key label. and instead of a key, mouse pointer buttons can be specified by "Pointer_Button1" and up, like "Shift+Pointer_Button3".
  • program options — program is the name of the executable or its path. it may start with a tilde or an environment variable, which will be expanded 🧚. the options are passed as arguments to the program.
  • runonce — an alternative to key. its syntax is:
runonce "hotkey" "wmclass" program options

here wmclass is the resource name and/or class. the class must be prefixed by a dot. the program is only run when no other application window with the same wmclass exists. and heads up: icewm ignores key repeat events for this hotkey. 🙈

  • switchkey — an alternative to key. in this case the program must print on standard output the definition of a dynamic icewm-menu(1). this menu will presented as a popup menu. it's giving dropdown but make it unix.
also!! to include a double quote literally, as part of your program arguments, escape it with a backslash. a double-quoted string can be continued on the next line using a backslash-newline, but this is unnecessary as lines can be of arbitrary length. so like, don't worry about line length, she's flexible 💖

🎀 EXAMPLES 🎀

following is the example keys file that ships with icewm(1). i'm including it whole because it's iconic and you need it:

# This is an example for IceWM's hotkey definition file.
#
# A list of all valid keyboard symbols can be found in
# /usr/include/X11/keysymdef.h, XF86keysym.h, ...
# Omit the XK_ prefixs and replace XF86XK_ prefixes by XF86.
# Valid modifiers are Alt, AltGr, Ctrl, Shift, Meta, Super, Hyper.
#
key "Alt+Ctrl+t" xterm
key "Alt+Ctrl+b" xdg-open about:blank
key "Alt+Ctrl+s" xdg-open https://www.google.com

key "Super+KP_Subtract" amixer sset PCM 5%-
key "Super+KP_Add" amixer sset PCM 5%+

# "Multimedia key" bindings for XFree86. Gather the
# keycodes of your advanced function keys by watching the
# output of the xev command whilst pressing those keys
# and map those symbols using xmodmap.

key "XF86AudioLowerVolume" amixer sset PCM 5%-
key "XF86AudioRaiseVolume" amixer sset PCM 5%+
key "XF86AudioMute" amixer sset PCM 0%
key "XF86HomePage" xdg-open about:blank
key "XF86Search" xdg-open https://www.google.com
key "XF86Eject" eject

# display and select monitor setup configurations
switchkey "Super+p" icewm-menu-xrandr

# display and select from all terminals
switchkey "Super+q"     icesh -Z switchmenu

following shows how to add mouse button bindings on the root window to change the current workspace rolling the mouse wheel on the desktop. yes, scroll to switch workspaces, we stan 🖱️✨

key "Pointer_Button4"   icesh goto prev
key "Pointer_Button5"   icesh goto next

and these are key bindings for single window tile operations to replace the KeyWinArrange key bindings from the preferences file — window tiling era, we love to see it 🫶

key "Ctrl+Alt+KP_Home"  icesh -f sizeto 49% 49% top left
key "Ctrl+Alt+KP_Up"    icesh -f sizeto 100% 49% top left
key "Ctrl+Alt+KP_Prior" icesh -f sizeto 49% 49% top right
key "Ctrl+Alt+KP_Right" icesh -f sizeto 49% 100% top right
key "Ctrl+Alt+KP_Next"  icesh -f sizeto 49% 49% bottom right
key "Ctrl+Alt+KP_Down" icesh -f sizeto 100% 49% bottom left
key "Ctrl+Alt+KP_End"   icesh -f sizeto 49% 49% bottom left
key "Ctrl+Alt+KP_Left"  icesh -f sizeto 49% 100% top left
key "Ctrl+Alt+KP_Begin" icesh -f sizeto 49% 49% center

🍓 FILES 🍓

locations for the keys file are as follows:

$ICEWM_PRIVCFG/keys
$XDG_CONFIG_HOME/icewm/keys
$HOME/.icewm/keys
/usr/etc/icewm/keys
/usr/share/icewm/keys

the locations are searched in the order listed; the first file found is read and the remainder ignored. so like, first one wins, no merging, no drama 💀

🌈 SEE ALSO 🌈

  • icewm(1). that's your other bestie, go read it too.

👑 AUTHOR 👑

Brian Bidulock <mailto:bidulock@openss7.org>. legend behavior, honestly.

💜 LICENSE 💜

IceWM is licensed under the GNU Library General Public License. see the COPYING file in the distribution for the full thing 📄.

ok that's the whole page bestie, you're officially a keys file expert. go bind something unhinged to Super+ and text me about it 💖

and that's a wrap on icewm 4.1.0, dated 2026-08-06 🌸 — manual page ICEWM-KEYS(5) out, slay 💅✨

📦 where this page comes from