wmctrl - interact with a EWMH/NetWM compatible X Window Manager.
is a command that can be used to interact with an X Window manager
that is compatible with the EWMH/NetWM specification. wmctrl
the window manager for information, and it can request that certain window
management actions be taken.
is controlled entirely by its command line arguments. The command
line arguments are used to specify the action to be performed (with options
that modify behavior) and any arguments that might be needed to perform the
The following sections define the supported actions and options. Arguments to
the actions and options are written in the form <ARGNAME>
descriptions below. The detailed syntax for writing arguments are in a single
section dedicated to that purpose.
The following command line arguments can be specified to invoke a wmctrl
action. Only one action can be executed with the invocation of the
- -a <WIN>
- Switch to the desktop containing the window
<WIN>, raise the window, and give it focus.
- -b ( add | remove | toggle),prop1
- Add, remove, or toggle up to two window properties
simultaneously. The window that is being modified must be identified with
a -r action. The property change is achived by using the EWMH
_NET_WM_STATE request. The supported property names (for prop1 and
prop2) are modal, sticky, maximized_vert,
maximized_horz, shaded, skip_taskbar,
skip_pager, hidden, fullscreen, above and
below. Two properties are supported to allow operations like
maximizing a window to full screen mode. Note that this action is made up
of exactly two shell command line arguments.
- -c <WIN>
- Close the window <WIN> gracefully.
- List all desktops managed by the window manager. One line
is output for each desktop, with the line broken up into space separated
columns. The first column contains an integer desktop number. The second
column contains a '*' character for the current desktop, otherwise it
contains a '-' character. The next two columns contain the fixed string
DG: and then the desktop geometry as
'<width>x<height>' ( e.g. '1280x1024').
The following two columns contain the fixed string VP: and then the
viewport position in the format '<y>,<y>' (
e.g. '0,0'). The next three columns after this contains the fixed
string WA: and then two columns with the workarea geometry as
'X,Y and WxH' ( e.g. '0,0 1280x998').
The rest of the line contains the name of the desktop (possibly containing
- -e <MVARG>
- Resize and move a window that has been specified with a
-r action according to the <MVARG> argument.
- -g w,h
- Change the geometry (common size) of all desktops so they
are w pixels wide and h pixels high. w and h
must be positive integers. A window manager may ignore this request.
- Print help text about program usage.
- -I name
- Set the icon name (short title) of the window specified by
a -r action to name.
- -k ( on | off )
- Turn on or off the window manager's "show the
desktop" mode (if the window manager implements this feature).
- List the windows being managed by the window manager. One
line is output for each window, with the line broken up into space
separated columns. The first column always contains the window identity as
a hexadecimal integer, and the second column always contains the desktop
number (a -1 is used to identify a sticky window). If the -p option
is specified the next column will contain the PID for the window as a
decimal integer. If the -G option is specified then four integer
columns will follow: x-offset, y-offset, width and height. The next column
always contains the client machine name. The remainder of the line
contains the window title (possibly with multiple spaces in the title).
- Display information about the window manager and the
- -n N
- Change the number of desktops to N (a non-negative
- -N name
- Set the name (long title) of the window specified by a
-r action to name.
- -o x,y
- Change the viewport for the current desktop. The values
x and y are numeric offsets that specify the position of the
top left corner of the viewport. A window manager may ignore this request.
- -r <WIN>
- Specify a target window for an action.
- -R <WIN>
- Move the window <WIN> to the current desktop,
raise the window, and give it focus.
- -s <DESK>
- Switch to the desktop <DESK>.
- -t <DESK>
- Move a window that has been specified with the -r
action to the desktop <DESK>.
- -T name
- Set the both the name (long title) and icon name (short
title) of the window specified by a -r action to name. This
action is like using the -N and -I actions at the same time
(which would otherwise be impossible since wmctrl can execute only
one action at a time).
The following options modify the default actions, or they modify the
interpretation of arguments.
- Window name arguments (<WIN>) are to be
treated as exact window titles that are case sensitive. Without this
options window titles are considered to be case insensitive substrings of
the full window title.
- Include geometry information in the output of the -l
- Interpret window arguments (<WIN>) as a
numeric value rather than a string name for the window. If the numeric
value starts with the prefix '0x' it is assumed to be a hexadecimal
- Include PIDs in the window list printed by the -l
action. Prints a PID of '0' if the application owning the window does not
- Override auto-detection and force UTF-8 mode.
- Provide verbose output. This is really useful when
debugging wmctrl itself.
- -w [ <WORKAROUND>[,<WORKAROUND>]...
- Use workarounds specified in the argument.
- Include WM_CLASS in the window list or interpret
<WIN> as the WM_CLASS name.
- A Desktop is always specified by an integer which
represents the desktop numbers. Desktop numbers start at 0.
- A move and resize argument has the format
All five components are integers. The first value, g, is the
gravity of the window, with 0 being the most common value (the default
value for the window). Please see the EWMH specification for other
- The four remaining values are a standard geometry
specification: x,y is the position of the top left
corner of the window, and w,h is the width and height
of the window, with the exception that the value of -1 in any position is
interpreted to mean that the current geometry value should not be
- This argument specifies a window that is the target of an
action. By default the argument is treated as if were a string, and
windows are examined until one is found with a title the contains the
specified string as a substring. The substring matching is done in a case
insensitive manner. The -F option may be used to force exact, case
sensitive title matching. The option -i may be used to interpret
the window target as a numeric window identity instead of a string.
- The window name string :SELECT: is treated
specially. If this window name is used then wmctrl waits for the
user to select the target window by clicking on it.
- The window name string :ACTIVE: may be used to
instruct wmctrl to use the currently active window for the action.
- There is only one work around currently implemeted. It is
specified by using the string DESKTOP_TITLES_INVALID_UTF8 and it
causes the printing of non-ASCII desktop tiles correctly when using Window
Getting a list of windows managed by the window manager
- wmctrl -l
Getting a list of windows with PID and geometry information.
- wmctrl -p -G -l
Going to the window with a name containing 'emacs' in it
- wmctrl -a emacs
Shade a window with a title that contains the word 'mozilla'
- wmctrl -r mozilla -b add,shaded
Close a very specifically titled window sticky
- wmctrl -F -c 'Debian bug tracking system - Mozilla'
Toggle the 'stickiness' of a window with a specific window identity
- wmctrl -i -r 0x0120002 -b add,sticky
Change the title of window to a specified string but choose the window by
clicking on it
- wmctrl -r :SELECT: -T "Selected Window"
is a useful dialog program for building scripts with
Some examples of EWMH/NetWM compatible window managers include recent versions
of Enlightenment, Icewm, Kwin, Sawfish and Xfce.
wmctrl was written by Tomas Styblo <email@example.com>.
This manual page was written by Shyamal Prasad <firstname.lastname@example.org>
for the Debian project (but may be used by others).