News Migration Tutorial Objects herbstluftwm(1) herbstclient(1)

herbstluftwm NEWS — History of user-visible changes

See the MIGRATION file for changes that introduced incompatibility to older versions.

Current git version

  • New herbstclient mode --binary-pipe which allows to send multiple commands through a single herbstclient instance.

  • CSS-inspired theme engine (new attributes, theme.style_override)

  • New client attribute sticky (does not react yet to EWMH requests)

Release 0.9.5 on 2022-07-30

  • Key binds for release events.

  • The Setting smart_frame_surroundings has been changed to accept the following new values: off, hide_all, and hide_gaps. Setting it to hide_gaps will only hide frame gaps when applicable, hide_all and off mirror the old behaviour with regards to true and false.

  • New format %{ } for easier attribute access in the sprintf command

  • New setting show_frame_decorations that controls when frame decorations are shown. This should be used instead of the old always_show_frame

  • New frame attribute content_geometry

  • New tag attribute at_end

  • New monitor attribute content_geometry

  • New attribute panels.geometry_fallback

  • Fix bug in ipc protocol for big-endian systems

Release 0.9.4 on 2022-03-16

  • Tabbed window titles in the max layout algorithm (controllable via the tabbed_max setting)

  • Directionally moving through a max layout is possible via focus / shift by adding --level=tabbed (only for tabbed_max) or --level=any (any max layout).

  • New decoration setting title_when to control, when window titles and tabs are shown.

  • New decoration settings title_depth and title_align.

  • New decoration settings for configuring unselected tabs: tab_color, tab_outer_width, tab_outer_color, tab_title_color

  • New autostart object with attributes path, running, pid, last_status

  • New client attribute floating_effectively and associated X11 properties HLWM_FLOATING_WINDOW and HLWM_TILING_WINDOW

  • New foreach command line flags: --filter-name=, --recursive, --unique

  • The spawn command now prints an error message on exec failure

  • New read-only client attribute decoration_geometry.

  • New rule condition fixedsize

  • New attribute decorated to disable window decorations

  • The cursor shape now indicates resize options.

  • New setting ellipsis

  • Floating clients can now be dragged between monitors via the mouse

  • Frames can be simultaneously resized in x and y direction with the mouse.

  • Bug fixes:

    • Update floating geometry if a client’s size hints change

    • Correct alpha value handling: if compositor is detected, premultiply rgb values with the alpha value

  • New dependency: xfixes

Release 0.9.3 on 2021-05-15

  • herbstclient prints error messages always on stderr and normal output always on stdout (before, both were printed to the same channel).

  • True transparency support for frame and client decorations (requires a compositor like picom, compton, or xcompmgr)

  • Colors contain alpha-values (format #RRGGBBAA)

  • Do not draw frame background behind clients (so for semi-transparent client decorations, one does not see the frame decoration behind but the wallpaper instead)

  • New command line option --replace for replacing an existing window manager.

  • New command list_clients.

  • The frame attributes (selection, algorithm, fraction, split_type) are now writable.

  • New objects for panels (under panels, exposing attributes instance, class, geometry, winid)

  • The setting monitors_locked is now explicitly an unsigned integer.

  • The setting default_frame_layout now holds an algorithm name.

  • New client attributes:

    • floating_geometry holding the client’s floating size (writable).

    • content_geometry holding the geometry of the application’s content.

  • The shift command now moves the window to a neighboured monitor if the window cannot be moved within a tag in the desired direction.

  • New command lower to lower a window in the stack.

  • The cycle_value command now expects an attribute (and only works for settings for compatibility).

  • New object types containing documentation on (attribute-) types.

  • New command attr_type printing the type of a given attribute.

  • New client alias last-minimized and longest-minimized for focusing and unminimizing minimized clients.

  • Relative values for integer attributes (+=N and -=N)

  • The cycle command now also cycles through floating windows.

  • The rule command now reports errors already during rule creation.

  • In rule consequences, toggle is not allowed anymore.

  • New rule consequences:

    • floating_geometry for setting the attribute of the same name (i.e. position and size of the new client)

  • The python bindings automatically convert from and to python’s types

  • Bug fixes:

    • Fix mistakenly transparent borders of argb clients

  • New dependency: xrender

Release 0.9.2 on 2021-02-17

  • Client window titles (controlled by the theme attributes title_height, title_color, title_font)

  • New command help for live documentation on the object tree

  • New watch command that emits hooks when attribute values change.

  • The lock_tag attribute is now writable.

  • New geometry attribute for monitors.

  • Bug fixes:

    • Correctly interpret _NET_WM_STRUT. This fixes panels that leave a bit of space between the panel and the monitor edge and also panels between two monitors.

    • Correctly handling minimized clients when removing a tag.

    • Preserve stacking order when changing the floating state of a tag

    • Update frame objects correctly in the commands mirror and rotate

  • New dependencies: xft, freetype

Release 0.9.1 on 2020-12-28

  • Client minimization (controlled by the attribute minimized of every client)

  • The index attribute of tags is now writable. This allows adjusting the order of existing tags.

  • New child object focused_client for each tag object.

  • New child object focused_frame for the tiling object of each tag object.

  • New child object parent_frame for each client providing the frame the client sits in

  • New command mirror

  • New command apply_tmp_rule

  • The apply_rules command now reports parse errors

  • Reserve space for panels that do not set _NET_WM_STRUT e.g. conky windows of type dock.

  • Only build json object doc if WITH_DOCUMENTATION is activated

  • Bug fixes:

    • When hiding windows, correctly set their WM_STATE to IconicState (we set it to Withdrawn state before, which means "unmanaged" and thus is wrong). This may require restarting pagers when upgrading hlwm live.

    • Fix crash in split explode

    • split explode preserves the window focus (as in v0.7.2 and before)

Release 0.9.0 on 2020-10-31

  • When an application fails to focus itself (because focus_stealing_prevention is active), then the window is marked as urgent.

  • New optional argument for the split command for splitting non-leaf frames

  • Frame objects: the frame layout can be introspected via the tiling object present in each tag, e.g.: tags.focus.tiling.

  • New command foreach for iterating over objects

  • New attribute urgent_count for tags, counting the number of urgent clients on a tag

  • New rule consequence floatplacement that updates the placement of floating clients (floatplacement=smart for little overlap, floatplacement=center for centering) or leaves the floating position as is (floatplacement=none)

  • New rule condition pgid

  • New format specifier %c in the sprintf command (useful in combination with foreach)

  • The new_attr command now also accepts an initial value

  • React to a change of the floating_focused attribute of the tag object

  • New frame index character p for accessing the parent frame

  • Object tree documentation as a json file

  • Bug fixes:

    • Fix wrong behaviour in cycle_layout in the case where the current layout is not contained in the layout list passed to cycle_layout.

    • Fix handling of delta -1 in focus_monitor and cycle_monitor

    • Fixed precision decimals in the layout tree (more reliable in- and output of fractions in frame splits)

    • Fixes in

Release 0.8.3 on 2020-06-06

  • Bug fixes:

    • Fix race condition in focus_follows_mouse handling

Release 0.8.2 on 2020-05-04

  • Selection of empty frames by the mouse (by click or by hover if focus_follows_mouse is enabled)

  • The commands close_and_remove / close_or_remove act like close for floating clients

  • The decoration window allows focusing, moving, and resizing the client via the mouse (as known from standard floating window managers)

  • Improved herbstclient tab completion for the fish shell

  • Bug fixes:

    • Fix a crash in the error handler when a invalid monitor name is passed. (Affects list_padding move_monitor rename_monitor lock_tag unlock_tag)

    • Fix the type of WM_STATE

    • The client attributes sizehints_tiling and sizehints_floating are now writable

    • Fix EWMH urgency change for clients without WM hints set

    • Fix the exit code of the focus command

Release 0.8.1 on 2020-04-21

  • the frame index e refers to the first empty frame (e.g. rule index=e places new windows in empty frames, if possible)

  • new setting hide_covered_windows to improve the appearance when used with a compositor.

  • resize floating windows with the same command (resize) as in tiling mode and thus the same keybindings as in tiling mode. Therefore, the fractiondelta parameter to the resize command is now optional.

  • keybind now checks that the bound command exists.

  • cycle_all (Alt-Tab) now also traverses floating clients

  • new setting auto_detect_panels controlling the panel detection algorithm.

  • improved herbstclient tab completion for the fish shell

  • Bug fixes:

    • Handle the regular expression "" correctly, since the grammar of extended regular expressions does not allow "".

    • Error handling for the lack of xrandr

    • Fixes to make it compile on other systems and architecture

Release 0.8.0 on 2020-04-09

  • single window floating (every client has an attribute floating which can be set at run time and via the rule consequence floating=on)

  • monitor detection via xrandr

  • detection of external panels

  • new command: apply_rules

  • new command: export (convenience wrapper around setenv)

  • new client attribute: keys_inactive (negation of keymask)

  • new command: drag (initiates moving/resizing a window by mouse)

  • if tags have been configured through EWMH before herbstluftwm starts (from a previous running window manager), then herbstluftwm re-uses these tags (start with --no-tag-import to disable this)

  • The build system is now cmake. See the INSTALL file if you need to compile herbstluftwm yourself.

  • the remove command now tries to preserve the focus and the client arrangement. Intuitively speaking, remove is undoing a frame split.

  • Many boolean style settings were formerly of type int. Now, these are boolean settings.

  • The toggle command only works for boolean settings. For the former behavior for int-typed settings, use cycle_value.

  • Writing %% in the sprintf format string now gives a literate %, just as printf. Formerly it stayed %%.

  • The keybind command now accepts all valid key symbols, even if they are not present on the current keyboard layout at the time of setup.

  • the rules are also applied to those clients that change their WM_CLASS after being shown already.

  • detect_monitors has an additional --list-all parameter

  • do not change the focus (for focus_follows_mouse=1) when an unmanaged dialog (e.g. a rofi menu or a notification) closes.

  • list_rules now prints regex-based rule conditions with ~ instead of =

  • new attributes on every monitor for pad_up pad_down pad_left pad_right

  • new flag --exit-on-xerror (to be used in automated testing only)

  • Formerly, double dots in object paths were allowed (similar to double slashes in file paths in unix). Right now, they are only allowed at the end (which is necessary for the tab-completion of attr):

    • monitors is valid

    • monitors. is valid

    • monitors.. is valid

    • is valid

    • is invalid

Release 0.7.2 on 2019-05-28

  • When herbstluftwm is not running and herbstclient is called, the absent herbstluftwm is detected instead of hanging forever.

  • Close window on _NET_CLOSE_WINDOW. This makes closing windows via ewmh panels work.

  • Fix return code of remove_attr

  • Fix error when unmanaging clients

  • Some typo fixes in the documentation

Release 0.7.1 on 2018-08-09

  • Many bugfixes:

    • Fix Xlib race condition


    • etc

  • New setting: verbose

  • Fix the initial floating position of new windows by taking their position relative to the nearest hlwm monitor.

  • new example scripts:


Release 0.7.0 on 2016-02-04

  • Handle EWMH request _NET_WM_MOVERESIZE more conform

  • Make tag objects accessible by their index

  • Automatically unmanage desktop windows (e.g. xfdesktop), and force them to stay below all other windows.

  • new command: close_and_remove

  • new herbstclient flags: --last-arg --print0

  • new example scripts:




    • (new subcommand "select_here")

Release 0.6.2 on 2014-03-27

Two bug fixes:

  • A crash has been fixed. It could be triggered by changing a non-callback settings attribute e.g. settings.raise_on_focus

  • The dialog re-mapping-problem has been fixed. So now, applications can show the same dialogs again after the dialog has been closed (e.g. the connection window of qjackctl).

Release 0.6.1 on 2014-03-25

  • directional shift of floating windows

  • fix crash of directional focus

  • document theme.minimal

Release 0.6.0 on 2014-03-19

  • Add window decorations, configurable via the theme-object

  • The tag attributes curframe_windex and curframe_wcount have been removed, they are replaced by the more general attributes frames.focus.windex frames.focus.wcount.

  • new example script:

  • if swap_monitors_to_get_tag is set to 0, then focus the other monitor if the desired tag is shown on another monitor instead of doing nothing

  • new split mode: auto

  • new attribute monitors.count indicating the number of monitors

  • new settings object with an attribute for each setting.

  • directional focus for floating clients, i.e. switch between floating windows via focus left|right|up|down. It also raises the freshly focused window.

  • directional monitor focusing

  • new detect_monitors flags: --list -l --no-disjoin while detect_monitors does disjoin_rects on the detected monitors per default.

  • For each client a keymask can be given. A keymask is a regular expression, that is matched against the string representation of a keybinding. If it matches, the keybinding is enabled for this client, otherwise not. The default is an empty keymask ("") that matches all keybindings, so no bindings are masked out by default. A keymask is a client attribute, and can be set by a client rule.

  • add completion to the mousebind command

  • add mouse function call to call commands on mouse button press

  • add setting update_dragged_clients

  • new rule consequence: monitor

  • new command: try

  • new command: silent

Release 0.5.3 on 2013-12-24

  • make window floating faster, by dropping old motion events

  • new rule flag: prepend

  • close now accepts an arbitrary window id as a parameter

  • Also allow decimal window ids for commands accepting a window id, like raise, jump, close

  • new split modes, i.e. parameters to the split command: bottom, right (indicating the relative location of the new empty frame)

  • new split mode: explode

  • make fraction parameter for the split command optional

  • respect size hints in floating and tiling mode

  • new setting: frame_transparent_width

  • frame_bg_transparent: instead of copying the pixmap from the root window achieve transparency by cutting out a rectangle from the center of frames using the Shape Extension of X.

  • Make respecting of sizehints configurable for tiling and floating mode via the client properties sizehints_tiling and sizehints_floating

  • new setting: pseudotile_center_threshold

  • new command: cycle_frame

  • new object attribute type: color

Release 0.5.2 on 2013-06-23


  • cycle_all now raises the focused client.

  • focus a client on its tag after moving it there (by shift_to_monitor or move)

  • disallow focus_follows_mouse if the focus change hides another window (e.g. an pseudotiled window in the max layout). In that case an extra click is required to change the focus.

  • new command complete_shell for posix shell specific completion

  • add completion for the rule command

  • add completion for keycombinations in keybind

  • add completion for setenv, getenv and unsetenv

  • the hook consequence now also tells the window id that triggerd the rule

  • new command: echo

  • new commands: true false

  • rule labels: rules can be given a label with the label property. The label can be printed to stdout using the printlabel flag to the rule command. Unrule command accepts a label to remove all rules with that label.

  • new command: list_rules

  • allow true/false as arguments to commands accepting boolean values. This affects the commands: floating, fullscreen, pseudotile and rule.

  • new command: new_attr, remove_attr, get_attr, set_attr

  • new command: substitute, sprintf, mktemp

Release 0.5.1 on 2013-01-05


  • new command: use_previous

  • Makefile: new target: install-nodoc — install without man/html-docs

  • fixup of the + flag in tag_status

  • fixup of the example script

  • announce it if the tag changes due to remove_monitor

Release 0.5.0 on 2012-12-31

Incompatible changes:

  • The setting focus_follows_shift has been removed. The behaviour now is set like it were set to 1; the focus always follows the shift now.


  • new settings: wmname, mouse_recenter_gap

  • hook togglehidepanel: the default also accepts the parameters "current" or a certain monitor index

  • align captions of the tree output (commands: layout, stack) better by inserting a space in front of every caption

  • let new clients and monitors (and other items that are stacked) appear on top of the stacking order

  • chaining of commands now is possible with the new command: chain

  • new commands: and or negate

  • tag switch locking for monitors. The new lock_tag and unlock_tag commands control, whether tag switching operations for a monitor are allowed.

  • set the urgent flag on _NET_WM_STATE_DEMANDS_ATTENTION

  • clear the urgent flag on window focus

  • new command: list_padding

  • new commands: getenv/setenv/unsetenv

  • new rule: ewmhnotify

  • floating, fullscreen, pseudotile: default to toggle if no argument is given

  • add error messages for herbstclient

  • new commands: focus_edge, shift_edge

  • new command: shift_to_monitor

  • optional names for monitors, new command rename_monitor

  • new consequence: hook

  • new example script: which provides a q3-like terminal

Release: 0.4.1 on 2012-08-30

This fixes some build system issues:

  • Separate CFLAGS and CPPFLAGS

  • Add patch level to the version number

  • Only use MACH if really needed

  • Honor CPPFLAGS

Release: 0.4 on 2012-08-18

Changes that require user interaction on upgrade:

  • the setting window_gap is now called frame_gap

Other changes:

  • new setting window_gap which controls the gap between windows within one frame

  • new setting: frame_padding

  • new command: close_or_remove

  • new flags - and % for tag_status for multi monitor handling

  • toggle default panel on hook togglehidepanel

  • new setting: window_border_urgent_color

  • new command: set_monitors

  • new command: disjoin_rects

  • new command: jumpto

  • use clock_get_time on systems with a mach kernel (typically Mac OS X). This lets herbstluftwm run on Mac systems again.

  • fix many memory leaks.

  • new command line flag --skip-visible for use_index and move_index

  • new command: detect_monitors, to detect Xinerama monitors automatically

  • new ewmh feature: react to _NET_WM_DESKTOP client messages

  • new command: rotate

  • new setting: auto_detect_monitors

  • only one Makefile for herbstluftwm and herbstclient. The herbstclient binary now is put in the main directory.

  • new settings: smart_frame_surroundings and smart_window_surroundings

  • new settings: window_border_inner_color and window_border_inner_width

  • new settings: frame_border_inner_color and frame_border_inner_width

  • new option --skip-invisible for cycle_all

  • cycle_layout now offers to cycle through a custom list of layouts

  • add completion for +1 and -1 to many commands: cycle, cycle_all, cycle_monitor, cycle_layout, split and use_index

  • start system wide autostart file if there is no working user defined one

  • clients are restored (i.e. managed) from _NET_CLIENT_LIST even if they are not visible

  • do proper window and monitor stacking, this also introduces:

    • new command: raise_monitor

    • new setting: raise_on_focus_temporarily

    • new command: stack

  • new command: focus_nth

  • new command: bring

  • respect the WM_TAKE_FOCUS atom, this fixes keyboard focus issues with many (mostly Java/swing based) applications

  • new rule consequences: switchtag, ewmhrequests

Release 0.3 on 2012-04-12


  • new hook: window_title_changed

  • hook focus_changed now also reports the window title

  • the setting ignore_class is removed, because this also can be done by rules. You can replace a line like set ignore_class "$foo" in your autostart by rule class~"$foo" manage=off

  • remember the value when toggling a setting and restore it on next toggle

  • new command: cycle_value

  • new commands: use_index, move_index

  • recursive command completion for keybind

  • new rule condition: title

  • in the default autostart:

    • new green and gray color theme

    • use/move was replaced by use_index/move_index

  • proper signal handling: map all windows on SIGINT,SIGQUIT,SIGTERM

  • respect the initial fullscreen state of new clients on startup (as it is set in the _NET_WM_STATE property)

  • monitor locking mechanism, i.e. a new setting: monitors_locked with its accessors lock and unlock and the command line argument -l and --locked

Release 0.2 on 2012-01-25

Small bugfixes and major features:

  • new command: monitor_rect

  • let fork less often

  • set clients to fullscreen

  • new client layouting algorithm: grid layout

  • new command argument: keyunbind --all

  • new command: pseudotile (tile client but keep its floating size)

  • new command: list_keybinds

  • new hook: focus_changed

  • client rules with:

    • condition: class

    • condition: instance

    • condition: pid

    • condition: maxage

    • condition: windowtype

    • condition: windowrole

    • operator: = (equals)

    • operator: ~ (regex-matching)

    • flag: once

    • flag: not (negation of conditions)

    • consequence: tag

    • consequence: focus

    • consequence: index (where to insert a new client in layout tree)

    • consequence: pseudotile

    • consequence: fullscreen

    • consequence: manage (whether window will be managed)

  • basic ewmh features:


    • the following client messages are handled: _NET_ACTIVE_WINDOW _NET_CURRENT_DESKTOP _NET_WM_STATE: fullscreen

Release 0.1 on 2011-10-02

Initial release. The tiling algorithm and many things are working. But some things like EWMH or rules aren’t implemented yet (See BUGS file for a list of planned features). Currently implemented features are:

  • basic tiling concept

  • floating mode (with border snapping)

  • calling herbstluftwm internal commands with herbstclient

  • change keybindings/mousebindings at runtime

  • change/get settings (e.g. colors) at runtime

  • add/remove monitors at runtime

  • wmexec into other window manager

  • dump/load tiling layouts to/from a string

  • bash/zsh tab completion for herbstclient

  • hook system: let herbstclient listen for internal events

  • provide an easy way to build an own panel (using herbstclient hooks/commands) (there is also an example

  • give information about urgent state of clients