Current version: 1.07 (ChangeLog)


wmctrl is a UNIX/Linux command line tool to interact with an EWMH/NetWM compatible X Window Manager.

The tool provides command line access to almost all the features defined in the EWMH specification. It can be used, for example, to get information about the window manager, to get a detailed list of desktops and managed windows, to switch and resize desktops, to make windows full-screen, always-above or sticky, and to activate, close, move, resize, maximize and minimize them.

The command line access to these window management functions makes it easy to automate and execute them from any application that is able to run a command in response to an event.

Please note that wmctrl only works with window managers that implement the EWMH specification. The tool is known to work - either fully or partially - with the following window managers:

  • blackbox >= 0.70
  • icewm
  • kwin (the default WM for KDE)
  • metacity (the default WM for GNOME)
  • openbox >= 3
  • sawfish
  • fvwm >= 2.5
  • waimea
  • pekwm
  • enlightenment >= 0.16.6
  • xfce >= 4
  • fluxbox >= 0.9.6
  • matchbox
  • window maker >= 0.91

In some of these window managers, EWMH is supported only in their current unstable/beta/developer releases (01/2005). Three simple criteria were chosen for including a window manager in the list above. The window manager must at least:

  • provide a list of windows and desktops
  • be able to activate a window
  • support desktop switching

Notably missing are the following, mostly "light-weight" window managers, which are not yet supported. Their EWMH implementation is either non-existent, incomplete or buggy:

  • afterstep 2.00 beta1 (incomplete)
  • ratpoison 1.3.0 (non-existent)
  • ion (non-existent)
  • pwm (non-existent)
  • evilwm (non-existent)
  • flwm (non-existent)
  • windowlab (non-existent)
  • ctwm (non-existent)

None of the lists above is exhaustive.


Usage: wmctrl [OPTION]...
  -m                   Show information about the window manager and
                       about the environment.
  -l                   List windows managed by the window manager.
  -d                   List desktops. The current desktop is marked
                       with an asterisk.
  -s <DESK>            Switch to the specified desktop.
  -a <WIN>             Activate the window by switching to its desktop and
                       raising it.
  -c <WIN>             Close the window gracefully.
  -R <WIN>             Move the window to the current desktop and
                       activate it.
  -r <WIN> -t <DESK>   Move the window to the specified desktop.
  -r <WIN> -e <MVARG>  Resize and move the window around the desktop.
                       The format of the <MVARG> argument is described below.
  -r <WIN> -b <STARG>  Change the state of the window. Using this option it's
                       possible for example to make the window maximized,
                       minimized or fullscreen. The format of the <STARG>
                       argument and list of possible states is given below.
  -r <WIN> -N <STR>    Set the name (long title) of the window.
  -r <WIN> -I <STR>    Set the icon name (short title) of the window.
  -r <WIN> -T <STR>    Set both the name and the icon name of the window.
  -k (on|off)          Activate or deactivate window manager's
                       "showing the desktop" mode. Many window managers
                       do not implement this mode.
  -o <X>,<Y>           Change the viewport for the current desktop.
                       The X and Y values are separated with a comma.
                       They define the top left corner of the viewport.
                       The window manager may ignore the request.
  -n <NUM>             Change number of desktops.
                       The window manager may ignore the request.
  -g <W>,<H>           Change geometry (common size) of all desktops.
                       The window manager may ignore the request.
  -h                   Print help.

  -i                   Interpret <WIN> as a numerical window ID.
  -p                   Include PIDs in the window list. Very few
                       X applications support this feature.
  -G                   Include geometry in the window list.
  -x                   Include WM_CLASS in the window list or
                       interpret <WIN> as the WM_CLASS name.
  -u                   Override auto-detection and force UTF-8 mode.
  -F                   Modifies the behavior of the window title matching
                       algorithm. It will match only the full window title
                       instead of a substring, when this option is used.
                       Furthermore it makes the matching case sensitive.
  -v                   Be verbose. Useful for debugging.
  -w <WA>              Use a workaround. The option may appear multiple
                       times. List of available workarounds is given below.

  <WIN>                This argument specifies the window. By default it's
                       interpreted as a string. The string is matched
                       against the window titles and the first matching
                       window is used. The matching isn't case sensitive
                       and the string may appear in any position
                       of the title.

                       The -i option may be used to interpret the argument
                       as a numerical window ID represented as a decimal
                       number. If it starts with "0x", then
                       it will be interpreted as a hexadecimal number.

                       The special string ":SELECT:" (without the quotes)
                       may be used to instruct wmctrl to let you select the
                       window by clicking on it.

                       The special string ":ACTIVE:" (without the quotes)
                       may be used to instruct wmctrl to use the currently
                       active window for the action.

  <DESK>               A desktop number. Desktops are counted from zero.

  <MVARG>              Specifies a change to the position and size
                       of the window. The format of the argument is:


                       <G>: Gravity specified as a number. The numbers are
                          defined in the EWMH specification. The value of
                          zero is particularly useful, it means "use the
                          default gravity of the window".
                       <X>,<Y>: Coordinates of new position of the window.
                       <W>,<H>: New width and height of the window.

                       The value of -1 may appear in place of
                       any of the <X>, <Y>, <W> and <H> properties
                       to left the property unchanged.

  <STARG>              Specifies a change to the state of the window
                       by the means of _NET_WM_STATE request.
                       This option allows two properties to be changed
                       simultaneously, specifically to allow both
                       horizontal and vertical maximization to be
                       altered together.

                       The format of the argument is:


                       The EWMH specification defines the
                       following properties:

                           modal, sticky, maximized_vert, maximized_horz,
                           shaded, skip_taskbar, skip_pager, hidden,
                           fullscreen, above, below


  DESKTOP_TITLES_INVALID_UTF8      Print non-ASCII desktop titles correctly
                                   when using Window Maker.

The format of the window list:

  <window ID> <desktop ID> <client machine> <window title>

The format of the desktop list:

  <desktop ID> [-*] <geometry> <viewport> <workarea> <title>


  • I recommend checking out Zenity. It is an excellent tool to integrate the GUI and the command line.
  • The following command may be used to turn wmctrl and zenity into a simple tool to change the titles of windows:
    title=`zenity --entry --title "Change window title" \
        --text "New window title"`; \
        wmctrl -r :SELECT: -T "$title"
  • xosd displays text on your screen, sounds simple right ? The difference is it is unmanaged and shaped, so it appears transparent. It's excellent for notifications.
  • xclip is a command line tool that provides an interface to X server selections (clipboard).
  • devilspie is a window-matching utility. It can be configured to detect windows as they are created, and match the window to a set of rules. If the window matches the rules, it can perform a series of actions on that window.
  • xnee is a suite of programs that can record, replay and distribute user actions under the X11 environment. Think of it as a robot that can imitate the job you just did.
  • x2x allows the keyboard and mouse on one X display to control another (possibly remote) X display.
  • Xtail emulates the behaviour of "tail -f" on the root window (background) of an X session. It prints the end of a given file on the root window, tracks the changes to the file, and continuously prints any new content that is appended to the file. It's a useful tool to track logfiles.
  • XFree86 distribution contains a few useful command line utilities:
    • Xnest, xgamma, xev, xwininfo, xprop, xlsclients, xlsatoms, xdpyinfo, xset, xrandr, xlsfonts, xkill
  • Check out my GKrellM plugins:


Tomas Styblo <tripie@cpan.org>

The code is available under the GNU General Public License (GPL).

Tomas Styblo,
Feb 9, 2015, 11:37 AM
Tomas Styblo,
Feb 9, 2015, 11:37 AM