Section: User Commands (1)
Updated: December 12, 2004



wmctrl - interact with a EWMH/NetWM compatible X Window Manager. 


wmctrl[ options | actions ]...



wmctrlis a command that can be used to interact with an X Window managerthat is compatible with the EWMH/NetWM specification.wmctrlcan query the window manager for information, and it can requestthat certain window management actions be taken.

wmctrlis controlled entirely by its command line arguments. The command linearguments are used to specify the action to be performed (with optionsthat modify behavior) and any arguments that might be needed toperform the actions.

The following sections define the supported actions andoptions. Arguments to the actions and options are written in the form<ARGNAME>in the descriptions below. The detailed syntax for writing argumentsare in a single section dedicated to that purpose.



The following command line arguments can be specified to invoke awmctrlaction. Only one action can be executed with the invocation of thewmctrlcommand.

-a <WIN>
Switch to the desktop containing the window<WIN>,raise the window, and give it focus.

-b ( add | remove | toggle),prop1 [,prop2 ]
Add, remove, or toggle up to two window properties simultaneously. Thewindow that is being modified must be identified with a-r action. Theproperty change is achived by using the EWMH _NET_WM_STATErequest. The supported property names (forprop1 and prop2)aremodal, sticky, maximized_vert, maximized_horz,shaded, skip_taskbar, skip_pager, hidden,fullscreen, above and below.Two properties are supported to allow operations like maximizing awindow to full screen mode. Note that this action is made up ofexactly two shell command line arguments.

-c <WIN>
Close the window<WIN>gracefully.

List all desktops managed by the window manager. One line is outputfor each desktop, with the line broken up into space separatedcolumns. The first column contains an integer desktop number. Thesecond column contains a '*' character for the current desktop,otherwise it contains a '-' character. The next two columns contain thefixed stringDG:and then the desktop geometry as'<width>x<height>'(e.g. '1280x1024'). The following two columns contain the fixedstringVP:and then the viewport position in the format'<y>,<y>'(e.g. '0,0'). The next three columns after this contains thefixed stringWA: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 ofthe desktop (possibly containing multiple spaces).

-e <MVARG>
Resize and move a window that has been specified with a-raction 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 hmust 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-raction to name.

-k ( on | off )
Turn on or off the window manager's "show the desktop" mode (if thewindow manager implements this feature).

List the windows being managed by the window manager. One line isoutput for each window, with the line broken up into space separatedcolumns. The first column always contains the window identity as ahexadecimal integer, and the second column always contains the desktopnumber (a -1 is used to identify a sticky window). If the-poption is specified the next column will contain the PID for thewindow as a decimal integer. If the -Goption is specified then four integer columns will follow: x-offset,y-offset, width and height. The next column always contains the clientmachine 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 toN(a non-negative integer).

-N name
Set the name (long title) of the window specified by a-raction to name.

-o x,y
Change the viewport for the current desktop. The valuesx and yare numeric offsets that specify the position of the top left cornerof 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-raction to the desktop <DESK>.

-T name
Set the both the name (long title) and icon name (short title) of thewindow specified by a-raction to name.This action is like using the-N and -Iactions at the same time (which would otherwise be impossible sincewmctrlcan execute only one action at a time).



The following options modify the default actions, or they modify theinterpretation of arguments.

Window name arguments (<WIN>)are to be treated as exact window titles that are casesensitive. Without this options window titles are considered to becase insensitive substrings of the full window title.

Include geometry information in the output of the -laction.

Interpret window arguments (<WIN>)as a numeric value rather than astring name for the window. If the numeric value starts with theprefix '0x' it is assumed to be a hexadecimal number.

Include PIDs in the window list printed by the -laction. Prints a PID of '0' if the application owning the window doesnot support it.

Override auto-detection and force UTF-8 mode.

Provide verbose output. This is really useful when debuggingwmctrlitself.

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 thedesktop numbers. Desktop numbers start at 0.

A move and resize argument has the format 'g,x,y,w,h'.All five components are integers. The first value,g,is the gravity of the window, with 0 being the most common value (thedefault value for the window). Please see the EWMH specification forother values.
The four remaining values are a standard geometry specification:x,yis the position of the top left corner of the window, andw,his the width and height of the window, with the exception that thevalue of -1 in any position is interpreted to mean that the currentgeometry value should not be modified.

This argument specifies a window that is the target of an action. Bydefault the argument is treated as if were a string, and windows areexamined until one is found with a title the contains the specifiedstring as a substring. The substring matching is done in a caseinsensitive manner. The-Foption may be used to force exact, case sensitive title matching. Theoption-imay be used to interpret the window target as a numeric windowidentity instead of a string.
The window name string:SELECT:is treated specially. If this window name is used thenwmctrlwaits 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 byusing the stringDESKTOP_TITLES_INVALID_UTF8and it causes the printing of non-ASCII desktop tiles correctly whenusing Window Maker.



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 windowby clicking on it

wmctrl -r :SELECT: -T "Selected Window"


zenity(1)is a useful dialog program for building scripts withwmctrl.

Some examples of EWMH/NetWM compatible window managers include recentversions of Enlightenment, Icewm, Kwin, Sawfish and Xfce.  


wmctrl was written by Tomas Styblo <>.

This manual page was written by Shyamal Prasad <>for the Debian project (but may be used by others).




This document was created byman2html,using the manual pages.