GWM Manual Contents

GWM man page


gwm [-1DstqmFiawWIPr?] [-x screens] [-f profile] [-p path] [-d display]


The following command-line options3 are supported:

-f filename
Names an alternate file as a GWM startup file. Default is .gwmrc.gwm (note that the .gwm extension is optional, as for any WOOL file).

For instance, to use the Motif emulation package, type gwm -f mwm.

-p path
Gives the path to be searched for WOOL or bitmap files when loaded, including the startup file. Overrides the setting by the environment variable GWMPATH. Defaults to
.:$HOME:$HOME/gwm:GWMDIR, where GWMDIR is the local directory where GWM is installed (normally, /usr/local/lib/X11/gwm).

You can append or prepend a path to the current path by preceding the path given as argument to the -p option by + (for appending) or - (for prepending). For instance, if you want to search the directory /usr/local/gwm before the standard ones (including your homedir), just say: -p -/usr/local/gwm.

-d display
Specifies the name of the display whose windows must be managed, such as unix:0. The -d is optional, you can type gwm unix:0.

-x screens
Do not manage the screens given in the comma-separated list of numbers, as in: -x 2,5,3. Normally, GWM manages all the screens of the given display.

Manages only the given screen, e.g. gwm -1 foo:0.2 manages only the third screen of the display number 0 on the foo machine. Same as defining the GWM_MONOSCREEN shell variable.

Continues reading interactively WOOL expressions from the standard input and prints their result. Useful for testing interactively code. Recommended use of GWM is for instance to run it interactively in an xterm, with:
    xterm -title Gwm -e fep gwm -IP&

When used with -I, makes GWM issue a simple prompt displaying the current parenthese level.

Enables debugging mode for WOOL files. In this version the only effect of debug mode is to continue reading a file after a WOOL error occurred. Default behavior is to abort reading a file after an error. Thus, if you modified your profile and introduced an error, GWM will refuse to complete execution, use gwm -D to run it anyway.

Synchronize X calls, useful for debugging but slower.

Turns tracing on, as if you had done the call (trace t) in your profile.

(Quiet) Does not print startup banner, and sets the WOOL gwm-quiet variable to 1.

Maps all toplevel windows already on screen. Useful after unmapping some windows by accident.

Does not freeze the server during pop-up menus, move and resize of the windows, which is the default behavior.

Disables the setting of input focus by GWM (set-focus has no effects, except (set-focus ()), which resets the focus to PointerRoot) on a window, keypresses go to the window under the cursor. Very useful to debug profiles with only one screen.

Asynchronously handle moves and resizes, do not cancel a move or a resize operation if the user released the button before the grid appeared, which is the default behavior.

-k process-id
Kills a process once initialization is done. Takes a process id as an argument. When gwm has finished initializing, it sends a signal (SIGALRM by default, but this can be changed by -K, see below) to the given process. So, if you do the following lines:

sleep 15 & pid=$!
xterm -title Gwm -e fep gwm -k $pid -IP &
wait $pid

then your init shell script will pause until gwm has finished initializing.

-K signal
sets the signal to use (number) instead of SIGALRM for the -k option above.

Normally, when GWM starts and sees that another window manager has still the control of the display, gwm aborts with a warning message. Specifying -r makes it retrying till it can get control.

-w window-id
Makes GWM decorate only one window, given by its ID, a decimal number

Makes GWM decorate all windows on screen, even if another window manager is already in charge.


This, or any invalid option lists the available options and shows the default path defined at compile time by your local installer.

Shell variables

GWM can make use of the following shell variables:

for the path to search for files. If unset, defaults to .:$HOME:$HOME/gwm:GWMDIR, where GWMDIR is the local directory in which are installed all the standard GWM files. (Normally /usr/local/lib/X11/gwm). Overridden by the -p command line option.

for the name of the profile file. Defaults to .gwmrc.gwm. Overridden by the -f command line option.

for the name of the X11 display to use, such as unix:0.0. Overridden by the -d command line option.

if set will make GWM manage only the given screen.

By default, gwm sends silently one udp packet when started to the author with the hostname of the machine as contnts, to maintain some rough statistics of use. If you dont want this to happen, you can set either of these two variables to anything, or recompile with either of these preprocesssor symbols defined.


GWM needs at least one file for its startup, .gwmrc.gwm which must be in GWM's path. New users do not need one, since a default profile should already be present in the default path. The standard profile makes use of the .profile.gwm file in the home directory.

The value of the default path can be printed by calling GWM with the -? command line option.

The standard extensions used for GWM file names are:
.gwm   for WOOL files.
.xbm X11 BitMap files, such as those created with BITMAP(1).
.xpm for X11 PixMap files, which is an ASCII portable format for distributing color images (see the pixmap-load function).


The GWM command is a window manager client application of the X11 window server specified in the display argument (or the DISPLAY shell variable if no argument is given), extensible via a built-in lisp interpreter, WOOL (Window Object Oriented Lisp) used to build Wobs (Window OBjects) which are used to decorate the windows of the other X11 applications running on the display. GWM tries to enforce the ICCCM conventions to communicate between X11 clients and thus should be compatible with any well-behaved X11 application.

On startup, GWM interprets its profile to build wobs describing how to decorate user windows, which we will call Clients. Then it creates Windows around each client windows on the screens attached to the managed display. A Window is made of 4 (optional) Bars on the 4 sides of the window. Each of these bars is made of a variable number of Plugs, the most primitive wobs. Menus can then be made with a list of bars. To each of these objects is associated a fsm (Finite State Machine) describing their behavior in terms of WOOL code triggered by X or WOOL events.

When GWM wants to decorate a window, it calls the user-defined WOOL function describe-window which must return a list of two window descriptions (one for the window itself, and one for its icon) made by the window-make WOOL primitive describing the window. To build these descriptions the user can query the client window for any X11 properties and use the X11 Resource Manager to decide how to decorate it.

The screens must also be described by such a description that GWM will find by calling the user-defined WOOL function describe-screen for each managed screen.

Christophe Tronche,