Next Previous Contents

4. Configuration

Congratulations! Now you have IceWM up and running. You don't like the default look? Don't worry: This section is on customizing IceWM.

As it is the case with most Linux and Unix programs IceWM can be configured using plain text config files.

4.1 You mean I have to edit these files?

There is a lot of utilities nowadays. See utilities section - Tools for IceWM.

The config files need to be changed if you want to change IceWM's behavior. This does not necessarily mean that you have to use an editor for this - graphical configuration tools for IceWM are available, although IceWM doesn't feature in-built configuration. More about these tools in the Utilities section. Still hand editing of these files is most effective and you can find even more than you are looking for. To notify IceWM about the changes you've made just send it a SIGHUP or restart it from the Logout menu.

4.2 Where are the configuration files?

You could not find the config files? Maybe you were looking in wrong places - the location depends upon the method you used to install IceWM.

In a plain vanilla source install, the global version of the files will be located in /usr/local/share/icewm. If you installed the standard RPM, they will be in /usr/X11R6/lib/X11/icewm/ or /usr/local/lib/Xll/icewm/. The system wide configuration files for the Debian package seem to be in /etc/X11/icewm/. Generaly you can try to use locate icewm command to find parts of IceWM.

However, if you wish to make a configuration of your own you should not edit these global config files but create a subdirectory of your home directory called ~/.icewm/. Copy the system wide files to your local .icewm directory and edit these copies.

Note: You may have to alter the permissions of the copies in order to read and write to them.

4.3 The configuration files

You can customize IceWM by editing the following configuration files:


Controls the contents of the start menu


Controls the general behavior of IceWM


Controls which additional key combos are available to users


Controls the row of launcher icons on the taskbar and has the same syntax as the menu file


Controls the behavior of individual applications (as identified by the names of their respective windows)


Script or command (must be executable) executed by icewm-session on startup


IceWM theme path/name.


To override theme preferences.


The menu file controls the contents in your menu (You knew that, right?). It has the following syntax:

    prog Program Icon app -with -options

is a keyword, telling IceWM that it's a program entry. Other keywords are
to draw a separator and
menu Xyz folder_icon {
  prog ...
to open a new sub menu called Xyz.
is the name which will be shown in the menu. Enclose it in apostrophes if you need more than one word here.
will be used as the menu entry's icon, if a corresponding image is found in IceWM's IconSearchPath. And finally
app -with -options
is what's going to be started if a user chooses this entry.

Note that the menu only shows entries which are found in your PATH, IceWM is clever enough to omit non-usable entries.

There are also two advanced options runonce and

menuprogreload "title" icon_name timeout program_exec

runonce is used to start application only once - if its already running do not start it upon clicking. Runonce needs some other options - see manual. menuprogreload is used to created dynamic menus: timeout is integer value, it specifies minimum time interval (in seconds) between menu reloading. Zero value means updating menus every time when user click it.

This is an example by the author of this feature:

# - Process menu for IceWM.
# Written by Konstantin Korikov.
# This is test script that generates IceWM menu
# with running user process list. It uses menuprogreload
# feature of IceWM menu. To use this script, add followed
# line to ~/.icewm/menu or  ~/.icewm/toolbar
#   menuprogreload ps - 0

if [ $# = 1 ]; then
        set `ps -p $1 --no-header -o pid,%cpu,%mem,time`
        echo "prog 'CPU: $2%' - true"
        echo "prog 'MEM: $3%' - true"
        echo "prog 'TIME: $4' - true"
        echo "separator"
        for i in HUP INT KILL TERM; do
                echo "prog $i - kill -$i $1"
        ps -aU `id -ru` --no-headers -o '%p|%c' |
        awk -F '|' -v sc="$0" \
          '{ printf("menuprogreload \"%d %s\" - 0 %s %d\n", $1, $2, sc, $1) }'

Some more can be found in patch 993038 in IceWM patch tracker.


The preferences file is the main configuration file. The default file is pretty much self documenting, so go and have a look. In case you ever wondered about themes: they can define all the options you can use in this file - and their definitions override all your personal customization!


In the keys file one can define shortcuts for starting programs. The existing entries make clear what one has to define.


The toolbar file defines some buttons which can be clicked next to the menu in the toolbar. It uses the same format as the menu file. You can also have folders in the toolbar. The easiest way to do that is simply by copying a menu from the /menu file over to the /toolbar file.


The winoptions file can be used to define the appearance of X applications like on which desktop they should appear, if should have a border, menu, titlebar, etc.


The startup is a script (must be executable) that is executed by icewm-session command on startup.

It can look like this:

(sleep 2; psi&)&

Do not forget to make this file executable

$ chmod +x startup

Note: It is recommended to use '#!/bin/sh' as the first line, to use /bin/sh to execute the script.

Also make sure all applications are starting at background (&).


The theme file is new from IceWM 1.2.10. It specifies which theme should be used


# contains theme history (max. 10 lines).

The theme file is changed every time you switch theme in menu and selected theme is therefore used after IceWM restart.


The prefoverride file is new from IceWM 1.2.12. In this file you can specify any preference which will override any preference specified by theme or anything else. This is introduced to solve troubles with order of preferences interpretation and give a user possibility to customize global things he wants to have allways the same.

Next Previous Contents