Section: User Commands (1)
Updated: December 12, 2004
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.
can query 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 actions.
The following sections define the supported actions and
options. Arguments to the actions and options are written in the form
in the 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
action. Only one action can be executed with the invocation of the
- -a <WIN>
Switch to the desktop containing the window
raise the window, and give it focus.
- -b ( add | remove | toggle),prop1 [,prop2 ]
Add, remove, or toggle up to two window properties simultaneously. The
window that is being modified must be identified with a
property change is achived by using the EWMH _NET_WM_STATE
request. The supported property names (for
prop1 and prop2)
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
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
and then the desktop geometry as
(e.g. '1280x1024'). The following two columns contain the fixed
and then the viewport position in the format
(e.g. '0,0'). The next three columns after this contains the
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 multiple spaces).
- -e <MVARG>
Resize and move a window that has been specified with a
action according to the
- -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
- -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
option is specified the next column will contain the PID for the
window as a decimal integer. If the
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 environment.
- -n N
Change the number of desktops to
(a non-negative integer).
- -N name
Set the name (long title) of the window specified by a
- -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
to the current desktop, raise the window, and give it focus.
- -s <DESK>
Switch to the desktop
- -t <DESK>
Move a window that has been specified with the
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
This action is like using the
-N and -I
actions at the same time (which would otherwise be impossible since
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
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
Interpret window arguments
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 number.
Include PIDs in the window list printed by the
action. Prints a PID of '0' if the application owning the window does
not support it.
Override auto-detection and force UTF-8 mode.
Provide verbose output. This is really useful when debugging
- -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. Use -1 to pin to all
A move and resize argument has the format
All five components are integers. The first value,
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
The four remaining values are a standard geometry specification:
is the position of the top left corner of the window, and
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 modified.
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
option may be used to force exact, case sensitive title matching. The
may be used to interpret the window target as a numeric window
identity instead of a string.
The window name string
is treated specially. If this window name is used then
waits for the user to select the target window by clicking on it.
The window name string
may be used to instruct
to use the currently active window for the action.
There is only one work around currently implemeted. It is specified by
using the string
and it causes the printing of non-ASCII desktop tiles correctly when
using Window Maker.
Getting a list of windows managed by the window manager
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).