Install Now
bspwm - Binary space partitioning window manager
Contents
Common Definitions
DIR := north | west | south | east
CYCLE_DIR := next | prev
Contributors
• Steven Allen <steven at stebalien.com>
• Thomas Adam <thomas at xteddy.org>
• Ivan Kanakarakis <ivan.kanak at gmail.com>
Description
bspwm is a tiling window manager that represents windows as the leaves of a full binary tree.
It is controlled and configured via bspc.
Domains
NodeGeneralSyntax
node [NODE_SEL] COMMANDS
If NODE_SEL is omitted, focused is assumed.
Commands-f, --focus [NODE_SEL]
Focus the selected or given node.
-a, --activate [NODE_SEL]
Activate the selected or given node.
-d, --to-desktopDESKTOP_SEL [--follow]
Send the selected node to the given desktop. If --follow is passed, the focused node will stay
focused.
-m, --to-monitorMONITOR_SEL [--follow]
Send the selected node to the given monitor. If --follow is passed, the focused node will stay
focused.
-n, --to-nodeNODE_SEL [--follow]
Send the selected node on the given node. If --follow is passed, the focused node will stay
focused.
-s, --swapNODE_SEL [--follow]
Swap the selected node with the given node. If --follow is passed, the focused node will stay
focused.
-p, --presel-dir [~]DIR|cancel
Preselect the splitting area of the selected node (or cancel the preselection). If ~ is prepended
to DIR and the current preselection direction matches DIR, then the argument is interpreted as
cancel. A node with a preselected area is said to be in "manual insertion mode".
-o, --presel-ratioRATIO
Set the splitting ratio of the preselection area.
-v, --movedxdy
Move the selected window by dx pixels horizontally and dy pixels vertically.
-z, --resize top|left|bottom|right|top_left|top_right|bottom_right|bottom_left dxdy
Resize the selected window by moving the given handle by dx pixels horizontally and dy pixels
vertically.
-r, --ratioRATIO|(+|-)(PIXELS|FRACTION)
Set the splitting ratio of the selected node (0 < RATIO < 1).
-R, --rotate90|270|180
Rotate the tree rooted at the selected node.
-F, --fliphorizontal|vertical
Flip the the tree rooted at selected node.
-E, --equalize
Reset the split ratios of the tree rooted at the selected node to their default value.
-B, --balance
Adjust the split ratios of the tree rooted at the selected node so that all windows occupy the
same area.
-C, --circulate forward|backward
Circulate the windows of the tree rooted at the selected node.
-t, --state [~](tiled|pseudo_tiled|floating|fullscreen)
Set the state of the selected window. If ~ is present and the current state matches the given
state, then the argument is interpreted as the last state.
-g, --flag hidden|sticky|private|locked|marked[=on|off]
Set or toggle the given flag for the selected node.
-l, --layer below|normal|above
Set the stacking layer of the selected window.
-i, --insert-receptacle
Insert a receptacle node at the selected node.
-c, --close
Close the windows rooted at the selected node.
-k, --kill
Kill the windows rooted at the selected node.
DesktopGeneralSyntax
desktop [DESKTOP_SEL] COMMANDS
If DESKTOP_SEL is omitted, focused is assumed.
COMMANDS-f, --focus [DESKTOP_SEL]
Focus the selected or given desktop.
-a, --activate [DESKTOP_SEL]
Activate the selected or given desktop.
-m, --to-monitorMONITOR_SEL [--follow]
Send the selected desktop to the given monitor. If --follow is passed, the focused desktop will
stay focused.
-s, --swapDESKTOP_SEL [--follow]
Swap the selected desktop with the given desktop. If --follow is passed, the focused desktop will
stay focused.
-l, --layoutCYCLE_DIR|monocle|tiled
Set or cycle the layout of the selected desktop.
-n, --rename <new_name>
Rename the selected desktop.
-b, --bubbleCYCLE_DIR
Bubble the selected desktop in the given direction.
-r, --remove
Remove the selected desktop.
MonitorGeneralSyntax
monitor [MONITOR_SEL] COMMANDS
If MONITOR_SEL is omitted, focused is assumed.
Commands-f, --focus [MONITOR_SEL]
Focus the selected or given monitor.
-s, --swapMONITOR_SEL
Swap the selected monitor with the given monitor.
-a, --add-desktops <name>...
Create desktops with the given names in the selected monitor.
-o, --reorder-desktops <name>...
Reorder the desktops of the selected monitor to match the given order.
-d, --reset-desktops <name>...
Rename, add or remove desktops depending on whether the number of given names is equal, superior
or inferior to the number of existing desktops.
-g, --rectangle WxH+X+Y
Set the rectangle of the selected monitor.
-n, --rename <new_name>
Rename the selected monitor.
-r, --remove
Remove the selected monitor.
QueryGeneralSyntax
query COMMANDS [OPTIONS]
Commands
The optional selectors are references.
-N, --nodes [NODE_SEL]
List the IDs of the matching nodes.
-D, --desktops [DESKTOP_SEL]
List the IDs (or names) of the matching desktops.
-M, --monitors [MONITOR_SEL]
List the IDs (or names) of the matching monitors.
-T, --tree
Print a JSON representation of the matching item.
Options-m,--monitor [MONITOR_SEL], -d,--desktop [DESKTOP_SEL], -n, --node [NODE_SEL]
Constrain matches to the selected monitor, desktop or node. The descriptor can be omitted for -M,
-D and -N.
--names
Print names instead of IDs. Can only be used with -M and -D.
WmGeneralSyntax
wm COMMANDSCommands-d, --dump-state
Dump the current world state on standard output.
-l, --load-state <file_path>
Load a world state from the given file. The path must be absolute.
-a, --add-monitor <name> WxH+X+Y
Add a monitor for the given name and rectangle.
-O, --reorder-monitors <name>...
Reorder the list of monitors to match the given order.
-o, --adopt-orphans
Manage all the unmanaged windows remaining from a previous session.
-h, --record-history on|off
Enable or disable the recording of node focus history.
-g, --get-status
Print the current status information.
-r, --restart
Restart the window manager
RuleGeneralSyntax
rule COMMANDSCommands-a, --add (<class_name>|*)[:(<instance_name>|*)[:(<name>|*)]] [-o|--one-shot]
[monitor=MONITOR_SEL|desktop=DESKTOP_SEL|node=NODE_SEL] [state=STATE] [layer=LAYER] [split_dir=DIR]
[split_ratio=RATIO]
[(hidden|sticky|private|locked|marked|center|follow|manage|focus|border)=(on|off)]
[rectangle=WxH+X+Y]
Create a new rule.
-r, --remove ^<n>|head|tail|(<class_name>|*)[:(<instance_name>|*)[:(<name>|\*)]]...
Remove the given rules.
-l, --list
List the rules.
ConfigGeneralSyntax
config [-m MONITOR_SEL|-d DESKTOP_SEL|-n NODE_SEL] <setting> [<value>]
Get or set the value of <setting>.
SubscribeGeneralSyntax
subscribe [OPTIONS] (all|report|monitor|desktop|node|...)*
Continuously print events. See the EVENTS section for the description of each event.
Options-f, --fifo
Print a path to a FIFO from which events can be read and return.
-c, --countCOUNT
Stop the corresponding bspc process after having received COUNT events.
QuitGeneralSyntax
quit [<status>]
Quit with an optional exit status.
Environment Variables
BSPWM_SOCKET
The path of the socket used for the communication between bspc and bspwm. If it isn’t defined, then
the following path is used: /tmp/bspwm<host_name>_<display_number>_<screen_number>-socket.
Events
report
See the next section for the description of the format.
monitor_add<monitor_id><monitor_name><monitor_geometry>
A monitor is added.
monitor_rename<monitor_id><old_name><new_name>
A monitor is renamed.
monitor_remove<monitor_id>
A monitor is removed.
monitor_swap<src_monitor_id><dst_monitor_id>
A monitor is swapped.
monitor_focus<monitor_id>
A monitor is focused.
monitor_geometry<monitor_id><monitor_geometry>
The geometry of a monitor changed.
desktop_add<monitor_id><desktop_id><desktop_name>
A desktop is added.
desktop_rename<monitor_id><desktop_id><old_name><new_name>
A desktop is renamed.
desktop_remove<monitor_id><desktop_id>
A desktop is removed.
desktop_swap<src_monitor_id><src_desktop_id><dst_monitor_id><dst_desktop_id>
A desktop is swapped.
desktop_transfer<src_monitor_id><src_desktop_id><dst_monitor_id>
A desktop is transferred.
desktop_focus<monitor_id><desktop_id>
A desktop is focused.
desktop_activate<monitor_id><desktop_id>
A desktop is activated.
desktop_layout<monitor_id><desktop_id>tiled|monocle
The layout of a desktop changed.
node_add<monitor_id><desktop_id><ip_id><node_id>
A node is added.
node_remove<monitor_id><desktop_id><node_id>
A node is removed.
node_swap<src_monitor_id><src_desktop_id><src_node_id><dst_monitor_id><dst_desktop_id><dst_node_id>
A node is swapped.
node_transfer<src_monitor_id><src_desktop_id><src_node_id><dst_monitor_id><dst_desktop_id><dst_node_id>
A node is transferred.
node_focus<monitor_id><desktop_id><node_id>
A node is focused.
node_activate<monitor_id><desktop_id><node_id>
A node is activated.
node_presel<monitor_id><desktop_id><node_id>(dirDIR|ratioRATIO|cancel)
A node is preselected.
node_stack<node_id_1>below|above<node_id_2>
A node is stacked below or above another node.
node_geometry<monitor_id><desktop_id><node_id><node_geometry>
The geometry of a window changed.
node_state<monitor_id><desktop_id><node_id>tiled|pseudo_tiled|floating|fullscreenon|off
The state of a window changed.
node_flag<monitor_id><desktop_id><node_id>hidden|sticky|private|locked|marked|urgenton|off
One of the flags of a node changed.
node_layer<monitor_id><desktop_id><node_id>below|normal|above
The layer of a window changed.
pointer_action<monitor_id><desktop_id><node_id>move|resize_corner|resize_sidebegin|end
A pointer action occurred.
Please note that bspwm initializes monitors before it reads messages on its socket, therefore the initial
monitor events can’t be received.
Exit Codes
If the server can’t handle a message, bspc will return with a non-zero exit code.
Name
bspwm - Binary space partitioning window manager
Node Flags
hidden
Is hidden and doesn’t occupy any tiling space.
sticky
Stays in the focused desktop of its monitor.
private
Tries to keep the same tiling position/size.
locked
Ignores the node--close message.
marked
Is marked (useful for deferred actions). A marked node becomes unmarked after being sent on a
preselected node.
urgent
Has its urgency hint set. This flag is set externally.
Options
-h
Print the synopsis and exit.
-v
Print the version and exit.
-cCONFIG_PATH
Use the given configuration file.
Pointer Bindings
click_to_focus
Focus the window (or the monitor) under the pointer if the value isn’t none.
pointer_modifier + button1
Move the window under the pointer.
pointer_modifier + button2
Resize the window under the pointer by dragging the nearest side.
pointer_modifier + button3
Resize the window under the pointer by dragging the nearest corner.
The behavior of pointer_modifier + button<n> can be modified through the pointer_action<n> setting.
Receptacles
A leaf node that doesn’t hold any window is called a receptacle. When a node is inserted on a receptacle
in automatic mode, it will replace the receptacle. A receptacle can be inserted on a node, preselected
and killed. Receptacles can therefore be used to build a tree whose leaves are receptacles. Using the
appropriate rules, one can then send windows on the leaves of this tree. This feature is used in
examples/receptacles to store and recreate layouts.
Report Format
Each report event message is composed of items separated by colons.
Each item has the form <type><value> where <type> is the first character of the item.
M<monitor_name>
Focused monitor.
m<monitor_name>
Unfocused monitor.
O<desktop_name>
Occupied focused desktop.
o<desktop_name>
Occupied unfocused desktop.
F<desktop_name>
Free focused desktop.
f<desktop_name>
Free unfocused desktop.
U<desktop_name>
Urgent focused desktop.
u<desktop_name>
Urgent unfocused desktop.
L(T|M)
Layout of the focused desktop of a monitor.
T(T|P|F|=|@)
State of the focused node of a focused desktop.
G(S?P?L?M?)
Active flags of the focused node of a focused desktop.
Selectors
Selectors are used to select a target node, desktop, or monitor. A selector can either describe the
target relatively or name it globally.
Selectors consist of an optional reference, a descriptor and any number of non-conflicting modifiers as
follows:
[REFERENCE#]DESCRIPTOR(.MODIFIER)*
The relative targets are computed in relation to the given reference (the default reference value is
focused).
An exclamation mark can be prepended to any modifier in order to reverse its meaning.
The following characters cannot be used in monitor or desktop names: #, :, ..
The special selector %<name> can be used to select a monitor or a desktop with an invalid name.
Node
Select a node.
NODE_SEL := [NODE_SEL#](DIR|CYCLE_DIR|PATH|any|first_ancestor|last|newest|
older|newer|focused|pointed|biggest|smallest|
<node_id>)[.[!]focused][.[!]active][.[!]automatic][.[!]local]
[.[!]leaf][.[!]window][.[!]STATE][.[!]FLAG][.[!]LAYER][.[!]SPLIT_TYPE]
[.[!]same_class][.[!]descendant_of][.[!]ancestor_of]
STATE := tiled|pseudo_tiled|floating|fullscreen
FLAG := hidden|sticky|private|locked|marked|urgent
LAYER := below|normal|above
SPLIT_TYPE := horizontal|vertical
PATH := @[DESKTOP_SEL:][[/]JUMP](/JUMP)*
JUMP := first|1|second|2|brother|parent|DIR
DescriptorsDIR
Selects the window in the given (spacial) direction relative to the reference node.
CYCLE_DIR
Selects the node in the given (cyclic) direction relative to the reference node within a
depth-first in-order traversal of the tree.
PATH
Selects the node at the given path.
any
Selects the first node that matches the given selectors.
first_ancestor
Selects the first ancestor of the reference node that matches the given selectors.
last
Selects the previously focused node relative to the reference node.
newest
Selects the newest node in the history of the focused node.
older
Selects the node older than the reference node in the history.
newer
Selects the node newer than the reference node in the history.
focused
Selects the currently focused node.
pointed
Selects the leaf under the pointer.
biggest
Selects the biggest leaf.
smallest
Selects the smallest leaf.
<node_id>
Selects the node with the given ID.
PathJumps
The initial node is the focused node (or the root if the path starts with /) of the reference desktop
(or the selected desktop if the path has a DESKTOP_SEL prefix).
1|first
Jumps to the first child.
2|second
Jumps to the second child.
brother
Jumps to the brother node.
parent
Jumps to the parent node.
DIR
Jumps to the node holding the edge in the given direction.
Modifiers
[!]focused
Only consider the focused node.
[!]active
Only consider nodes that are the focused node of their desktop.
[!]automatic
Only consider nodes in automatic insertion mode. See also --presel-dir under Node in the DOMAINS
section below.
[!]local
Only consider nodes in the reference desktop.
[!]leaf
Only consider leaf nodes.
[!]window
Only consider nodes that hold a window.
[!](tiled|pseudo_tiled|floating|fullscreen)
Only consider windows in the given state.
[!]same_class
Only consider windows that have the same class as the reference window.
[!]descendant_of
Only consider nodes that are descendants of the reference node.
[!]ancestor_of
Only consider nodes that are ancestors of the reference node.
[!](hidden|sticky|private|locked|marked|urgent)
Only consider windows that have the given flag set.
[!](below|normal|above)
Only consider windows in the given layer.
[!](horizontal|vertical)
Only consider nodes with the given split type.
Desktop
Select a desktop.
DESKTOP_SEL := [DESKTOP_SEL#](CYCLE_DIR|any|last|newest|older|newer|
[MONITOR_SEL:](focused|^<n>)|
<desktop_id>|<desktop_name>)[.[!]focused][.[!]active]
[.[!]occupied][.[!]urgent][.[!]local]
DescriptorsCYCLE_DIR
Selects the desktop in the given direction relative to the reference desktop.
any
Selects the first desktop that matches the given selectors.
last
Selects the previously focused desktop relative to the reference desktop.
newest
Selects the newest desktop in the history of the focused desktops.
older
Selects the desktop older than the reference desktop in the history.
newer
Selects the desktop newer than the reference desktop in the history.
focused
Selects the currently focused desktop.
^<n>
Selects the nth desktop. If MONITOR_SEL is given, selects the nth desktop on the selected
monitor.
<desktop_id>
Selects the desktop with the given ID.
<desktop_name>
Selects the desktop with the given name.
Modifiers
[!]focused
Only consider the focused desktop.
[!]active
Only consider desktops that are the focused desktop of their monitor.
[!]occupied
Only consider occupied desktops.
[!]urgent
Only consider urgent desktops.
[!]local
Only consider desktops inside the reference monitor.
Monitor
Select a monitor.
MONITOR_SEL := [MONITOR_SEL#](DIR|CYCLE_DIR|any|last|newest|older|newer|
focused|pointed|primary|^<n>|
<monitor_id>|<monitor_name>)[.[!]focused][.[!]occupied]
DescriptorsDIR
Selects the monitor in the given (spacial) direction relative to the reference monitor.
CYCLE_DIR
Selects the monitor in the given (cyclic) direction relative to the reference monitor.
any
Selects the first monitor that matches the given selectors.
last
Selects the previously focused monitor relative to the reference monitor.
newest
Selects the newest monitor in the history of the focused monitors.
older
Selects the monitor older than the reference monitor in the history.
newer
Selects the monitor newer than the reference monitor in the history.
focused
Selects the currently focused monitor.
pointed
Selects the monitor under the pointer.
primary
Selects the primary monitor.
^<n>
Selects the nth monitor.
<monitor_id>
Selects the monitor with the given ID.
<monitor_name>
Selects the monitor with the given name.
Modifiers
[!]focused
Only consider the focused monitor.
[!]occupied
Only consider monitors where the focused desktop is occupied.
Settings
Colors are in the form #RRGGBB, booleans are true, on, false or off.
All the boolean settings are false by default unless stated otherwise.
GlobalSettingsnormal_border_color
Color of the border of an unfocused window.
active_border_color
Color of the border of a focused window of an unfocused monitor.
focused_border_color
Color of the border of a focused window of a focused monitor.
presel_feedback_color
Color of the node--presel-{dir,ratio} message feedback area.
split_ratio
Default split ratio.
status_prefix
Prefix prepended to each of the status lines.
external_rules_command
Absolute path to the command used to retrieve rule consequences. The command will receive the
following arguments: window ID, class name, instance name, and intermediate consequences. The output
of that command must have the following format: key1=value1key2=value2... (the valid key/value
pairs are given in the description of the rule command).
automatic_scheme
The insertion scheme used when the insertion point is in automatic mode. Accept the following values:
longest_side, alternate, spiral.
initial_polarity
On which child should a new window be attached when adding a window on a single window tree in
automatic mode. Accept the following values: first_child, second_child.
directional_focus_tightness
The tightness of the algorithm used to decide whether a window is on the DIR side of another window.
Accept the following values: high, low.
removal_adjustment
Adjust the brother when unlinking a node from the tree in accordance with the automatic insertion
scheme.
presel_feedback
Draw the preselection feedback area. Defaults to true.
borderless_monocle
Remove borders of tiled windows for the monocle desktop layout.
gapless_monocle
Remove gaps of tiled windows for the monocle desktop layout.
top_monocle_padding, right_monocle_padding, bottom_monocle_padding, left_monocle_padding
Padding space added at the sides of the screen for the monocle desktop layout.
single_monocle
Set the desktop layout to monocle if there’s only one tiled window in the tree.
pointer_motion_interval
The minimum interval, in milliseconds, between two motion notify events.
pointer_modifier
Keyboard modifier used for moving or resizing windows. Accept the following values: shift, control,
lock, mod1, mod2, mod3, mod4, mod5.
pointer_action1, pointer_action2, pointer_action3
Action performed when pressing pointer_modifier + button<n>. Accept the following values: move,
resize_side, resize_corner, focus, none.
click_to_focus
Button used for focusing a window (or a monitor). The possible values are: button1, button2, button3,
any, none. Defaults to button1.
swallow_first_click
Don’t replay the click that makes a window focused if click_to_focus isn’t none.
focus_follows_pointer
Focus the window under the pointer.
pointer_follows_focus
When focusing a window, put the pointer at its center.
pointer_follows_monitor
When focusing a monitor, put the pointer at its center.
mapping_events_count
Handle the next mapping_events_count mapping notify events. A negative value implies that every event
needs to be handled.
ignore_ewmh_focus
Ignore EWMH focus requests coming from applications.
ignore_ewmh_fullscreen
Block the fullscreen state transitions that originate from an EWMH request. The possible values are:
none, all, or a comma separated list of the following values: enter, exit.
ignore_ewmh_struts
Ignore strut hinting from clients requesting to reserve space (i.e. task bars).
center_pseudo_tiled
Center pseudo tiled windows into their tiling rectangles. Defaults to true.
honor_size_hints
Apply ICCCM window size hints.
remove_disabled_monitors
Consider disabled monitors as disconnected.
remove_unplugged_monitors
Remove unplugged monitors.
merge_overlapping_monitors
Merge overlapping monitors (the bigger remains).
MonitorandDesktopSettingstop_padding, right_padding, bottom_padding, left_padding
Padding space added at the sides of the monitor or desktop.
DesktopSettingswindow_gap
Size of the gap that separates windows.
NodeSettingsborder_width
Window border width.
Stacking Layers
There’s three stacking layers: BELOW, NORMAL and ABOVE.
In each layer, the window are orderered as follow: tiled & pseudo-tiled < floating < fullscreen.
Synopsis
bspwm [-h|-v|-cCONFIG_PATH]
bspcDOMAIN [SELECTOR] COMMANDSbspcCOMMAND [OPTIONS] [ARGUMENTS]
Window States
tiled
Its size and position are determined by the window tree.
pseudo_tiled
A tiled window that automatically shrinks but doesn’t stretch beyond its floating size.
floating
Can be moved/resized freely. Although it doesn’t use any tiling space, it is still part of the window
tree.
fullscreen
Fills its monitor rectangle and has no borders.
PNG Icons
Emojis
