From Gentoo Wiki
Jump to: navigation, search
External resources

Openbox is a highly configurable, next generation window manager with extensive standards support.


Install x11-wm/openbox:

USE flag (what is that?) Default Recommended Description
branding No Yes Enable Gentoo specific branding
debug No Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see
imlib Yes Add support for imlib, an image loading and rendering library
nls Yes Add Native Language Support (using gettext - GNU locale utilities)
python_targets_python2_7 Yes Yes Build with Python 2.7
session Yes Enables support for session managers
startup-notification No Enable application startup event feedback mechanism
static-libs No Build static versions of dynamic libraries as well
svg No Add support for SVG (Scalable Vector Graphics)
xdg No Install the python xdg files for xdg autostart
root #emerge --ask x11-wm/openbox


There are four files to consider when configuring Openbox:

  • autostart
  • environment
  • menu.xml
  • rc.xml

Openbox installs these files to /etc/xdg/openbox/ To have Openbox use custom configurations for each user, copy the four configuration files above to the home directly of each user (~/.config/openbox/), then modify each according to the users' needs.

For example:

user $mkdir -p ~/.config/openbox/
user $cp /etc/xdg/openbox/* ~/.config/openbox/
user $vim ~/.config/openbox/autostart


To start Openbox it is possible to use a display manager or the startx command.

To use startx and with ConsoleKit support, setup ConsoleKit and create the following file:

FILE ~/.xinitrc Openbox with ConsoleKit example
exec ck-launch-session dbus-launch --sh-syntax --exit-with-session openbox-session


The autostart file is the ideal way to execute specific commands and programs when Openbox starts. It makes no difference if Openbox is started using the startx command or a display manager.

FILE ~/.config/openbox/autostart Openbox startup example
# Sets the wallpaper to an image of choice.
# Sets the DESKTOP_ENV variable to "OPENBOX"
# The following are examples on how to call programs;
# unless programs are called in a daemon mode like the 
# conky example below an ampersand (&) will need to be included 
# in order to start the command and fork it to the background
# See job control for more information.
conky --daemonize
# Waits one second then starts the NetworkManager applet.
sleep 1 && nm-applet --sm-disable &
# Starts a light-weight X11 desktop panel.
fbpanel &
# Starts a lightweight image viewer.
feh --bg-scale ~/Artwork/${wallpaper} &
# Starts a simple battery monitor for the system tray.
batti &
# Starts a program that turns on numlock in X (after the X server starts).
numlockx &


This is the ideal place to export global variables and configure the Openbox environment as appropriate:

FILE ~/.config/openbox/environment Openbox environment example
eval $(gpg-agent --daemon)
eval $(gnome-keyring-daemon)
if which dbus-launch >/dev/null && test -z "$DBUS_SESSION_BUS_ADDRESS"; then
       eval `dbus-launch --sh-syntax --exit-with-session`



The rc.xml file is used to specify key bindings and mouse bindings.

The following are modifier examples.

Key Description
S Shift key
C Ctrl key
A Alt key
W Super (windows) key
M Meta key
H Hyper key

To make a key binding, combine modifiers and a key. They are separated with the - (dash) sign.

Case matters! S (uppercase) equates to the Shift key while s (lowercase) is the s alphabet key.


Keybinding Modifier
Alt+o A-o
Ctrl+Alt+x C-A-x
Ctrl+Alt+Shift+y C-A-S-y
Shift+s S-s
Any custom key bindings should go between <keyboard> and </keyboard> tags in rc.xml.

To open xterm with Super+t, add the following to the rc.xml:

FILE ~/.config/openbox/rc.xml Xterm key binding example
<keybind key="W-t">
  <action name="Execute">

Keybinding menus is also possible. For example, bind Openbox's right click and middle click menus with the following statement

FILE ~/.config/openbox/rc.xml Root-Menu key bind example
<keybind key="W-x">
  <action name="ShowMenu">
<keybind key="W-z">
  <action name="ShowMenu">

In the above example, the right click menu is bound to a Super+x key press combination, and the middle click menu is bound to Super+z key press combo. It is useful to key bind applications especially when a user prefers to not use a panel program with Openbox.


Icons in the Openbox Menu

Since version 3.5.0, Openbox is able to have icons next to menu entries.

  1. To emerge Openbox with imlib support add imlib USE flag to x11-wm/openbox in /etc/portage/package.use
    root #echo "x11-wm/openbox imlib" >> /etc/portage/package.use
  2. Re-emerge Openbox so that support for the imlib USE flag is considered:
    root #emerge --ask --changed-use x11-wm/openbox
  3. Add a <showIcons>yes</showIcons> line to the <menu> section of the rc.xml file.
  4. Add in menu.xml icon="<path>" like this:
    FILE ~/.config/openbox/menu.xml Manually add icons to Openbox example
    <menu label="Shells" icon="/usr/share/icons/shell.png">
    <item label="xterm" icon="/usr/share/icons/xterm.png">
    	<action name="Execute">

See also

External resources