Settings Reference

This guide explains all bspwm configuration options with practical examples and recommendations. Settings are applied using bspc config either in your bspwmrc or dynamically at any time.

How Settings Work

Setting a Value

bspc config setting_name value

Getting the Current Value

bspc config setting_name

Scope-Specific Settings

Some settings can be applied globally or to specific monitors, desktops, or nodes:

# Global (all desktops)
bspc config window_gap 10

# Per-monitor
bspc config -m HDMI-1 top_padding 30

# Per-desktop
bspc config -d '^3' window_gap 0

# Per-node
bspc config -n focused border_width 4

Appearance Settings

These settings control how bspwm looks. Getting these right makes a huge difference in daily use.

Border Colors

Borders help you identify window states at a glance.

Setting Description
normal_border_color Border color for unfocused windows
active_border_color Border color for focused window on an unfocused monitor
focused_border_color Border color for the focused window on the focused monitor
presel_feedback_color Color of the pre-selection preview area

Colors use the #RRGGBB hexadecimal format.

Example configuration:

# Subtle unfocused, bright focused
bspc config normal_border_color '#444444'
bspc config active_border_color '#666666'
bspc config focused_border_color '#0088ff'
bspc config presel_feedback_color '#00ff88'

Recommendations:

  • Use a dim color for normal_border_color so unfocused windows fade into the background
  • Choose a distinctive focused_border_color that stands out immediately
  • If you only use one monitor, active_border_color won't be visible
  • Match presel_feedback_color to your overall color scheme

Border Width

bspc config border_width 2

The width in pixels of window borders. Common values:

  • 0 - No borders (requires other visual cues for focus)
  • 1 - Minimal, clean look
  • 2-3 - Balanced visibility
  • 4+ - Very prominent, useful for high-DPI displays

Per-node border width:

# Give the focused window a thicker border
bspc config -n focused border_width 4

Window Gap

bspc config window_gap 10

Pixels of space between tiled windows. This is a desktop-level setting.

Recommendations:

  • 0 - Maximum screen real estate
  • 5-10 - Slight separation, clean look
  • 15-20 - Prominent gaps, modern "rice" aesthetic
  • Larger gaps work better on large/high-DPI monitors

Different gaps per desktop:

# Full-screen desktop for videos with no gap
bspc config -d 'Video' window_gap 0

# Coding desktop with breathing room
bspc config -d 'Code' window_gap 15

Padding

Padding creates empty space at the edges of a monitor or desktop, typically used for panels/bars.

Setting Description
top_padding Space at the top (for top panel)
bottom_padding Space at the bottom (for bottom panel)
left_padding Space on the left
right_padding Space on the right 
# Reserve 30 pixels at top for polybar
bspc config top_padding 30

# Reserve space on both sides (for centered layout)
bspc config left_padding 200
bspc config right_padding 200

Per-monitor padding:

# Different bar heights on different monitors
bspc config -m 'eDP-1' top_padding 24
bspc config -m 'HDMI-1' top_padding 30

Behavior Settings

These settings control how bspwm behaves—how windows are inserted, focused, and managed.

Split Ratio

bspc config split_ratio 0.5

The default ratio when splitting a window. Value between 0 and 1.

  • 0.5 - Equal 50/50 splits (default)
  • 0.6 - New windows get 40%, existing get 60%
  • 0.52 - Slightly favor existing windows (golden ratio approximation: use 0.618)

Initial Polarity

bspc config initial_polarity first_child

When a window is added to a single-window tree, determines if it becomes the first or second child.

  • first_child - New window goes left/top
  • second_child - New window goes right/bottom (default)

This affects the initial direction of splits when you open your second window.

Automatic Scheme

bspc config automatic_scheme longest_side

How bspwm decides the split direction when automatically inserting windows:

Scheme Behavior
longest_side Split perpendicular to the longest side. Creates square-ish windows.
alternate Alternate between horizontal and vertical splits.
spiral Classic bspwm behavior, creates a spiral pattern.

Recommendations:

  • longest_side - Most intuitive for general use
  • spiral - Good for many small terminals
  • alternate - Predictable grid-like layouts

Removal Adjustment

bspc config removal_adjustment true

When true, closing a window adjusts its sibling to fill the space. When false, the sibling maintains its previous size.

Focus and Click Behavior

These settings control how focus changes and how mouse clicks interact with windows.

Click to Focus

bspc config click_to_focus button1

Which mouse button focuses a window when clicked:

  • none - Clicking doesn't change focus (use keybindings only)
  • button1 - Left click focuses
  • button2 - Middle click focuses
  • button3 - Right click focuses
  • any - Any mouse button focuses

Swallow First Click

bspc config swallow_first_click false

When click_to_focus is enabled:

  • true - The focusing click isn't passed to the application
  • false - The click both focuses AND is passed to the application

Set to true if you don't want accidental clicks when focusing (e.g., clicking a link just to focus the browser).

Focus Follows Pointer

bspc config focus_follows_pointer true

When true, moving the mouse over a window focuses it. No click required.

Recommendations:

  • true for keyboard-centric workflows—just point and type
  • false if you find it distracting or often accidentally move focus

Pointer Follows Focus

bspc config pointer_follows_focus false

When true, changing focus (via keyboard) moves the mouse pointer to the center of the newly focused window.

  • Useful with focus_follows_pointer to prevent focus from immediately jumping back
  • Can feel jarring if you're using the mouse

Pointer Follows Monitor

bspc config pointer_follows_monitor true

When switching monitors, move the pointer to the center of the target monitor.

Helpful in multi-monitor setups to prevent "losing" the cursor.

Pointer Actions

Configure what happens when you hold a modifier key and click/drag on windows.

Pointer Modifier

bspc config pointer_modifier mod4

The key to hold for pointer actions. Common values:

  • mod4 - Super/Windows key (recommended)
  • mod1 - Alt key
  • control - Control key

Pointer Actions

bspc config pointer_action1 move
bspc config pointer_action2 resize_side
bspc config pointer_action3 resize_corner

What each mouse button does when pointer_modifier is held:

Action Description
move Drag to move the window
resize_side Drag to resize by nearest edge
resize_corner Drag to resize by nearest corner
focus Just focus the window
none No action

Default setup:

  • mod4 + left-click - Move window
  • mod4 + middle-click - Resize by edge
  • mod4 + right-click - Resize by corner

Pointer Motion Interval

bspc config pointer_motion_interval 10

Minimum milliseconds between motion events when dragging. Lower = smoother but more CPU. Default is usually fine.

Monocle Layout Settings

The monocle layout shows one window at a time, maximized. These settings fine-tune its behavior.

Borderless Monocle

bspc config borderless_monocle true

Remove window borders in monocle layout. Since only one window is visible, borders are unnecessary.

Gapless Monocle

bspc config gapless_monocle true

Remove gaps in monocle layout, maximizing the single visible window.

Paddingless Monocle

bspc config paddingless_monocle false

Remove padding (including bar space) in monocle layout.

Warning: If true, the monocle window will cover your panel/bar.

Single Monocle

bspc config single_monocle false

Automatically enter monocle layout when a desktop has only one tiled window.

EWMH and External Integration

Settings for compatibility with panels, pagers, and other tools.

Ignore EWMH Focus

bspc config ignore_ewmh_focus false

When true, ignore focus requests from applications via EWMH.

Set to true if applications keep stealing focus unexpectedly.

Ignore EWMH Struts

bspc config ignore_ewmh_struts false

When true, ignore struts (reserved screen space) set by panels.

Usually leave false so panels correctly reserve their space.

Center Pseudo Tiled

bspc config center_pseudo_tiled true

Center pseudo-tiled windows in their tiling rectangles. Default is true.

Honor Size Hints

bspc config honor_size_hints false

Respect ICCCM size hints from applications (minimum/maximum size, resize increments).

  • true - Some windows may not fill their allocated space
  • false - Force windows to fill their space (may look wrong for some apps like terminals)

Monitor Management

Settings for handling monitor changes.

Remove Disabled Monitors

bspc config remove_disabled_monitors true

Treat disabled monitors as disconnected. Useful for laptop docking.

Remove Unplugged Monitors

bspc config remove_unplugged_monitors true

Automatically remove monitors when unplugged. Windows move to remaining monitors.

Merge Overlapping Monitors

bspc config merge_overlapping_monitors true

When monitors overlap, keep only the larger one. Helps with misconfigured xrandr setups.

External Rules Command

bspc config external_rules_command '/path/to/script.sh'

Path to a script that provides dynamic window rules. The script receives window information and outputs rule consequences.

Example script:

#!/bin/bash
# external_rules.sh

wid=$1
class=$2
instance=$3

# Float all windows with "dialog" in the instance name
if [[ "$instance" == *dialog* ]]; then
    echo "state=floating"
fi

# Send Spotify to desktop 10
if [[ "$class" == "Spotify" ]]; then
    echo "desktop=^10"
fi

This is more powerful than static rules because you can use any logic.

Example bspwmrc Settings

Here's a complete example settings section:

#!/bin/bash
# bspwmrc - settings section

# Appearance
bspc config border_width         2
bspc config window_gap           10
bspc config top_padding          30
bspc config bottom_padding       0
bspc config left_padding         0
bspc config right_padding        0

# Colors
bspc config normal_border_color   '#32344a'
bspc config active_border_color   '#444b6a'
bspc config focused_border_color  '#7aa2f7'
bspc config presel_feedback_color '#9ece6a'

# Behavior
bspc config split_ratio           0.52
bspc config automatic_scheme      longest_side
bspc config removal_adjustment    true

# Focus
bspc config focus_follows_pointer true
bspc config pointer_follows_focus false
bspc config click_to_focus        button1
bspc config swallow_first_click   false

# Pointer
bspc config pointer_modifier      mod4
bspc config pointer_action1       move
bspc config pointer_action2       resize_side
bspc config pointer_action3       resize_corner

# Monocle
bspc config borderless_monocle    true
bspc config gapless_monocle       true
bspc config paddingless_monocle   false
bspc config single_monocle        false

# Monitors
bspc config remove_disabled_monitors  true
bspc config remove_unplugged_monitors true
bspc config merge_overlapping_monitors true