---
name: "icewm-session"
section: "1"
platform: "linux"
package: "icewm"
version: "4.1.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/icewm-session"
---

# icewm-session(1)

### NAME

```
 icewm-session - X.Org session manager provider with IceWM
```

### SYNOPSIS

**icewm-session** \[*OPTIONS*\]

### DESCRIPTION

icewm-session is an implementation of a X.Org session manager and can be run from a X11 session setup. It runs **icewm** as default window manager and controls the life cycle of related support applications.

### OPTIONS

### SPECIFIC OPTIONS

- **-c**, **--config=FILE**

  Let IceWM load preferences from *FILE*.

- **-t**, **--theme=FILE**

  Let IceWM load the theme *FILE*.

- **-i**, **--icewm=FILE**

  Use *FILE* as the IceWM window manager.

- **-o**, **--output=FILE**

  Redirect all output to *FILE*. A leading tilde or environment variable is expanded.

- **-a**, **--alpha**

  Use a 32-bit visual for translucency.

- **-b**, **--nobg**

  Do not start icewmbg.

- **-n**, **--notray**

  Do not start icewmtray. This is only applicable if IceWM was explicitly configured to use an external icewmtray process.

- **-s**, **--sound**

  Also start icesound.

- **--replace**

  Replace an existing window manager.

### GENERAL OPTIONS

- **-d**, **--display**=*DISPLAY*

  Use *DISPLAY* to connect to the X server. If this option is missing then *DISPLAY* is read from the environment variable `"DISPLAY"`.

- **--sync**

  Use a slower synchronous mode communication with the *X11* server.

- **-h**, **--help**

  Give a list of all supported options and exit.

- **-V**, **--version**

  Print the program version and exit.

- **-C**, **--copying**

  Print copying permissions and exit.

### DEBUGGING OPTIONS

- **-v**, **---valgrind**

  Let `"/usr/bin/valgrind"` run icewm. Thoroughly examines the execution of icewm.

- **-g**, **---catchsegv**

  Let `"/usr/bin/catchsegv"` run icewm. Gives a backtrace if icewm segfaults.

### USAGE

On startup icewm-session executes the following steps. From the file *env* in the configuration directory it loads additional environment variables, if that file exists. Then it will start *icewmbg* to manage root background colors and images. It may also start *icesound*, if this was enabled at configuration time. Then *icewm* is started.

If there exists an executable script *startup* in the configuration directory, it will be executed. It may contain commands to initialize X11 settings with *xset*, load keyboard configuration, start a compositing manager like *compton* and load system tray applications.

When icewm exits, icewm-session will execute a *shutdown* script, if it exists in the configuration directory. When this finishes, icewm-session will terminate icewm, icewmbg and icesound. Finally, icewm-session will exit.

If the icewm process crashes then icewm-session will attempt to restart it. If two such crashes occur in a short period, then icewm-session will attempt to popup a dialog using either *yad*, *xmessage*, *kdialog* or *zenity*.  This dialog presents a choice between restarting icewm, starting a terminal, or abort execution of icewm-session.

### ENVIRONMENT

- **ICEWM\_OPTIONS**

  A space separated list of options that will be added to the command line invocation of *icewm*. This can be set in the *env* file.

### SEE ALSO

[**icewm**(1)](/icewm/1.md), [**icewm-env**(5)](/icewm-env/5.md), [**icewm-shutdown**(5)](/icewm-shutdown/5.md), [**icewm-startup**(5)](/icewm-startup/5.md), [**icewmbg**(1)](/icewmbg/1.md).

### BUGS

Please report bugs at \<https://github.com/ice-wm/icewm/issues\>.

### AUTHOR

Brian Bidulock \<mailto:bidulock@openss7.org\>.

See **--copying** for full copyright notice and copying permissions.

### LICENSE

**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.