IceWM man pages

View the Project on GitHub


icewm - lightweight X11 window manager


icewm [OPTIONS]


icewm is a lightweight window manager for the X11 window system. It aims to be small, fast and familiar to new users. icewm is called a re-parenting window manager, because it draws small frames around application windows. Windows are manipulated via the mouse by dragging or resizing this frame. It is also called a stacking window manager, because windows can overlap. Many windows may exist, some hidden behind others, while interaction takes place with the currently visible ones. icewm supports a configurable number of virtual desktops. It provides a task bar for monitoring applications and a pager to switch between desktops. icewm is largely compliant with the ICCCM 2.0, WinWM/WMH and NetWM/EWMH window manager specifications.

icewm was originally designed to emulate the look of Motif, OS/2 Warp 4, OS/2 Warp 3 and Windows 95. Since it has a theme engine other styles are possible. The installation comes with several configured themes. A menu allows to choose between themes.

Generally, it tries to make all functions available by both keyboard and mouse. Configuration is very good through various preferences files. However, configuring is not required: it works fine out of the box.


The icewm package includes several programs:



Each of the IceWM executables supports the following options:


The icewm program supports some additional options:



On startup icewm launches the task bar at the bottom of the screen. The task bar consists from left to right of the following components:

The Menu button in the lower left corner gives access to the icewm root menu. This menu has sub-menus to start applications, to control icewm settings, and the icewm Logout menu.

The Show Desktop button unmaps all application windows to fully uncover the desktop.

The Window List Menu button gives access to a menu with a list of active windows for the current work space and a list of work spaces with sub-menus for their active application windows.

The Toolbar is a list of icons for applications which are defined in the toolbar configuration file.

The Workspace List shows one button for each work space. The current work space is indicated by a pressed button. Pressing another work space button switches to that work space. The work spaces are defined in the preferences file. When PagerShowPreview is turned on a small graphical summary for each workspace is shown.

The Task Pane consists of a list of wide buttons for each application which is running on the current work space, or all workspaces if TaskBarShowAllWindows=1. Each task button shows the application icon and the application title. The active application is indicated by a pressed button. This is the application which has input focus. Pressing another button activates that application: it is brought to the foreground and receives input focus. Other mouse controlled activities on the window buttons are: dragging window buttons with the left mouse button to rearrange the order, closing the application window with Alt + middle button, lowering the application window with Ctrl + middle button, or bringing the application window to the current workspace with Shift + middle button if TaskBarShowAllWindows=1.

If there are not many application buttons then a stretch of plain task bar is visible. Clicking on it with the right mouse button gives the task bar menu. Even with a full task pane, this menu can be usually accessed by right-clicking the bottom right corner of the taskbar.

The Tray Applet shows system tray objects.

The APM Applet shows battery power status.

The Net Applet shows network activity. Network devices to monitor are given by the NetworkStatusDevice option.

The Memory Applet monitors memory usage.

The CPU Applet monitors processor utilization.

The Mailbox Applet monitors mailbox status changes. See the section MAILBOX MONITORING below.

The Clock Applet shows the current time and date. It is configured by the TimeFormat option.

The Task Bar Collapse button collapses the task bar and hides it.

Not all icewm applets may show up on the task bar. They must have been enabled during configuration of the icewm software. Their appearance is also controlled by options in the preferences file.


Of all visible windows only one can be the active window. This is the window which has input focus. It is the primary receiver of keyboard and mouse events and hence one can interact with the application which created that window. A primary task of a window manager is to allow the user to switch input focus between different windows. The primary means to do this is the mouse pointer. By moving the mouse pointer over the screen to another window, and perhaps also by clicking on a window, input focus can be directed.

The FocusMode option controls the way icewm gives input focus to applications. It is initialized by the focus_mode configuration file. The focus mode is set via the Focus menu. icewm supports six focus models:

Apart from the mouse, icewm supports changing input focus in two other ways. Both involve the keyboard. The first uses the QuickSwitch window. It is activated by pressing Alt+Tab or Alt+Shift+Tab. A window pops up in the centre of the screen with a narrow band over the next or previous window which will receive input focus when the Alt key is released. By repeatedly pressing Alt+Tab or Alt+Shift+Tab one can cycle through all windows.

The second keyboard method involves pressing Alt+Esc or Alt+Shift+Esc. Input focus is immediately changed to the next or previous window, which will be raised to make it fully visible.

And finally, there is another way which is a hybrid of keyboard and mouse control. It involves the QuickSwitch popup explained before, after pressing Alt+Tab and while still holding Alt a left click on one of the list items causes the activation of the related window.


A second important task of a window manager is to place new windows on the screen. By default icewm chooses a placement with minimal overlap, but this is determined by the SmartPlacement option in the preferences file. If SmartPlacement is turned off then windows are placed in sequence from left to right and top to bottom. One can also turn on ManualPlacement. Then new windows appear initially in the top left corner and the mouse cursor changes into a fist. By moving the fist cursor to a suitable location and clicking the new window will appear at the mouse click location.


Windows can overlap. Which window appears on top is determined by three features. Newer windows appear over older windows. By clicking on a window it is raised to the top. But both are overruled by the window layer. Windows can be placed in different layers via the Layers menu. Click with the right mouse button on the window frame and select Layer. From there choose one of seven window layers. These are ordered from higher to lower. Windows in higher layers appear over windows in lower layers.


icewm supports multiple virtual desktops called work spaces. A work space is like a screen where a subset of all application windows are mapped. Thanks to multiple work spaces we can more easily manage a large number of applications. The number of work spaces and their names are configurable in the preferences file through the WorkspaceNames option. By default four workspaces are created with the names 1, 2, 3 and 4 thus:

WorkspaceNames=" 1 ", " 2 ", " 3 ", " 4 "

This syntax is typical for icewm options which receive multiple values. It is a list of comma-separated values each of which can be quoted.

The work spaces are visible on the toolbar. One can switch to a different work space by pressing the work space button in the toolbar, but after becoming familiar with the ‘keyboard shortcuts’ below one will want to use a hotkey to choose a work space. If the EdgeSwitch options is enabled in the preferences file (with sub-options HorizontalEdgeSwitch and VerticalEdgeSwitch) then one can move to the next or previous workspace by moving the mouse to the edge of the screen. The ContinuousEdgeSwitch option enables continuous movement to subsequent workspaces. The EdgeSwitchDelay option says how long to wait before a change of workspace occurs.

To move an application window to a different work space one can use a keyboard shortcut. Another option is to select the Move To submenu in the window menu of the window frame.


If EnableAddressBar=1 then KeySysAddressBar=Alt+Ctrl+Space activates the address bar in the task bar. If ShowAddressBar=1 it is always shown. This is a command-line in the task bar where a shell command can be typed. Pressing Enter will execute the command. AddressBarCommand=/bin/sh will be used to execute the command. On Control+Enter the command is executed in a terminal as given by TerminalCommand. The address bar maintains a history which is navigable by the Up and Down keys. It supports file completion using Tab or Ctrl+I. A rich set of editing operations is supported, including cut-/copy-/paste-operations.


The window list window shows a list of all workspaces. For each workspace it shows the window titles of the windows which are mapped on it. The bottom entry reads All Workspaces. It holds the sticky windows. These windows are mapped in all workspaces.

The window list window is normally hidden. Choose one of the following four methods to make it visible:

A single-click on a window entry selects it. A group of windows can be selected by Shift+Pointer_Button1 or by dragging with the left mouse button. Use Ctrl+Pointer_Button1 to individually select windows in a multi-selection. A right mouse click over a selection will popup the system menu for this selection. To close the selected windows, press Delete. Press Shift+Delete to forcefully kill them. Right mouse click below the sticky windows for a menu with window arranging actions.

Double-click on a workspace to switch to it. Double-click on a window to activate it. Or navigate by arrow keys and press Enter. The space bar toggles a selection of a window. Ctrl+a and Ctrl+/ will select the entire list of windows. Ctrl+\\ deselects everything. Press the first letter of a window title to navigate to it and select it. If titles of multiple windows start with the same letter then repeatedly pressing the first letter cycles over those windows. Home selects the first entry and End the last. PageUp and PageDown move up or down by ten entries. Combine this with the Shift key to extend a selection over the range of motion.


The task bar can show one or more icons to reflect the status of a mailbox. The mailbox can be a local file or a remote POP or IMAP account. For this a couple of options must be set. First, TaskBarShowMailboxStatus must be enabled, which it is by default. Then the location of the mailbox must be set. Icewm first looks for MailBoxPath in preferences. If this is unset, it looks at the environment variables MAILPATH and MAIL. MailBoxPath may contain a space-separated list of mailboxes, while MAILPATH may contain a colon-separated list of mailboxes. If a mailbox starts with a slash /, then it is a local file, otherwise a URL. These are six examples of possible mailboxes:


The POP3S and IMAPS schemes use openssl for TLS/SSL encryption. Note that for IceWM to access Gmail you must first configure your Gmail account to enable POP3 or IMAP access. Make sure you have secure file permissions on your IceWM preferences file and the directory which contains it.

Reserved characters in the password, like slash, at and colon can be specified using escape sequences with a hexadecimal encoding like %2f for the slash or %40 for the at sign. For example, to hex-encode !p@a%s&s~ use this Perl snippet:

perl -e 'foreach(split("", $ARGV[0])) { printf "%%%02x", ord($_); };
print "\n";' '!p@a%s&s~'

Which will print:


This is the hex-encoded password. However, it is unwise to store a password in your preferences. Consider a wallet extension for IceWM.

IceWM will check a mailbox periodically. The period in seconds can be set by the MailCheckDelay option, which is 30 seconds by default.

Whenever new mail arrives, the mailbox icon will be highlighted. The color will indicate if the mail has been read or not. Hovering the mouse over the mailbox icon will show a tooltip with more details. A command can be also be run on new mail. Set the NewMailCommand option. Its environment will have these variables set by IceWM:


To control keyboard layouts on the task bar, define in preferences the option KeyboardLayouts to a comma-separated list of your preferred keyboard layouts. For example:


A keyboard layout can simply be a name. Usually this is a two-letter country code. See the directory /usr/share/X11/xkb/symbols for a list of available keyboard layouts for your system. If it is enclosed in double quotes, it can also be a space-separated list of command-line arguments to an invocation of the setxkbmap program.

The first layout is the default. It will be installed when icewm starts. The task bar will show the current keyboard layout. If an icon can be found for the first two letters of the layout, then that icon will be shown. Otherwise the first two letters of the name of the layout will be shown.

Click on the current keyboard layout to cycle through all the available keyboard layouts. Click with the right mouse button to open a menu of all available keyboard layouts.

It is also possible to configure a default keyboard layout for each program individually in the icewm-winoptions(5) file. Whenever such a program receives input focus, icewm will install this configured keyboard layout automatically. The keyboard status on the task bar will be updated to reflect this.

Please note that for keyboard layout switching to work, the setxkbmap program must be installed. To see your current keyboard layout settings, do setxkbmap -query.


icewm supports a large number of hotkeys to activate some behaviour with a single key combination. These are all configurable in the preferences file. Here we give their preferences name, followed by their default value in double quotes, and a short descriptions of their effect:


You can control windows by a modified mouse button press:

The title frame of a window also listens for mouse clicks. Left double clicking maximizes the window (TitleBarMaximizeButton=1). Middle double clicking rolls up the window (TitleBarRollupButton=2). Pressing a mouse button and moving it will move the window. Alt+Pointer_Button1 lowers the window.

When the mouse is on the window frame then a left click raises the window. Dragging with the left button down resizes the window. Clicking the right button pops up the context menu. Dragging with the right button moves the window.

Clicking on the desktop activates a menu. The middle button shows the window list (DesktopWinListButton=2). The right button shows the root menu (DesktopMenuButton=3). If you press Ctrl+Alt then the mouse wheel will focus all applications in turn.


icewm supports the following signals:



icewm looks for configuration files in the following directories, in the given order, until it finds one:




IceWM supports window opacity and transparency in connection with an external compositor like compton(1). If a client window sets the _NET_WM_WINDOW_OPACITY property on its window then icewm will copy this to the outer frame window where compton will read it to adjust the opacity of the client window. The opacity can also be controlled by icewm when this is configured in the icewm-winoptions(5) file. Another way is to use icewmhint(1) to preset the opacity level immediately before starting the application. The opacity level of running applications can always be queried or modified by icesh(1).

The _NET_WM_WINDOW_TYPE properties which icewm sets on its windows are DIALOG, NOTIFICATION, POPUP_MENU and TOOLTIP. The output of icesh windows shows their WM_CLASS values. These can be helpful to configure compton.


Examples of the above configuration files can be found in the default installation path or in the system-wide defaults. See the output of icewm --directories for their locations.


ICCCM 2.0: partial. NetWM/EWMH: extensive. See the file COMPLIANCE in the distribution for full details.


icehelp(1), icesh(1), icesound(1), icewm-env(5), icewm-focus_mode(5), icewm-keys(5), icewm-menu(5), icewm-menu-fdo(1), icewm-menu-xrandr(1), icewm-preferences(5), icewm-prefoverride(5), icewm-programs(5), icewm-session(1), icewm-set-gnomewm(1), icewm-shutdown(5), icewm-startup(5), icewm-theme(5), icewm-toolbar(5), icewm-winoptions(5), icewmbg(1), icewmhint(1), setxkbmap(1), Xorg(1), Xserver(1), xinit(1), xprop(1), xwininfo(1), wmctrl(1).


icewm had no known bugs at the time of release. Please report bugs for current versions to the source code repository at Github.


Brian Bidulock.

See –copying for full copyright notice and copying permissions.


IceWM is licensed under the GNU Library General Public License. See the COPYING file in the distribution or use the –copying flag to display copying permissions.

Index IceWM