The Openbox Configuration HOWTO
What is Openbox?
So, you've installed The X Server and
realised that TWM just isn't going to cut it for your needs. You may have also
had some experience with big desktop environments like KDE, GNOME, and Xfce. One component of those larger desktop
suites is called the window manager (or WM for short). A window manager is
responsible for the appearance and placement of the containers (or "windows")
inside which programs run. Openbox is a minimalistic, no-frills-attached window
Why should I use it?
Openbox, unlike the larger desktop environments, depends on very few libraries.
For that reason, it can provide a lightweight graphic environment that runs
very quickly, even on older hardware. Whether your hardware is old or new,
Openbox also provides a highly customisable and unobtrusive working
environment. That means that if you don't want or need a panel, taskbar, clock,
or any other program, those choices are yours to make!
Installation and configuration
After you have emerged and configured xorg-server, installing Openbox can
be done in one simple command:
Code Listing 2.1: Installing Openbox
# emerge -av openbox
Just like with other window managers and desktop environments, you will need to
tell the X Server to load Openbox automatically, by adding it to your
Code Listing 2.2: Adding Openbox to your .xinitrc
$ echo "exec openbox-session" >> ~/.xinitrc
This will automatically start your Openbox session when you type startx
at the terminal.
As each user has his or her own .xinitrc, you need to make sure to
issue that command as your user, not as root.
If you experience problems with automounting, or if you use dbus and ConsoleKit,
you may want to put exec ck-launch-session dbus-launch --sh-syntax
--exit-with-session openbox-session in your .xinitrc instead of
the default mentioned above.
You can also replace the KDE, GNOME, or Xfce default window manager with
Openbox by following the Openbox inside desktop
Now that you have emerged Openbox and added it to your .xinitrc,
go ahead and issue the startx command to see Openbox in action. As you
can see, the desktop is simply a cluttered mess! In following with the Openbox
philosophy, what you will see is a barebones environment from which you can
build your desktop completely to your liking.
Since you're looking at nothing more than a black screen, you may be wondering
where the menu is. If you click your right mouse button, you will notice that a
menu pops up in the location of your cursor. This menu is nothing more than an
example to illustrate the style of an Openbox menu. Since it is just an
example, none of the items in the menu will work unless you have actually
emerged those programs. In the next section, you will see how to create your
own menu that contains links to your programs.
If you click to view the menu and notice that there is nothing legible, you need
to install some fonts. Two common choices are media-fonts/corefonts and
Since the default Openbox menu is essentially useless to you for the reasons
mentioned above, it's time that we create one that will work. Everything in the
Openbox menu is written in the appropriately named menu.xml file,
which can be in the user-specific location of
~/.config/openbox/menu.xml, or in the system-wide location of
/etc/xdg/openbox/menu.xml. By default, the only
menu.xml file that is created is the system-wide one which applies
to all users on the system.
An easy way to get a basic menu file which you can modify is to use MenuMaker,
which will generate a menu.xml file based on the programs which
you currently have installed on your system. To do so, you must firstly emerge
Code Listing 2.3: Installing MenuMaker
# emerge menumaker
Once it is installed, make sure to logout of root, and back into your user
account. You then instruct MenuMaker to create a menu specifically using the
Openbox XML syntax:
Code Listing 2.4: Using MenuMaker to generate a basic Openbox menu.xml
$ mmaker -v OpenBox3
The generated menu will be located at
~/.config/openbox/menu.xml. You can then choose to leave it as
your user-specific menu.xml, or to additionally copy it to the
system-wide menu configuration as well:
Code Listing 2.5: Overwriting the default system-wide menu.xml files
# cp .config/openbox/menu.xml /etc/xdg/openbox/menu.xml
It is a good idea to use MenuMaker to generate a default menu, as it will have
the Openbox root-menu items. These items include a virtual desktop switcher,
and the commands to restart and exit your Openbox session.
When you open up the menu.xml file in your favourite editor (nano,
for example), you will notice that the XML tags used are very human-readable
and easily understandable. You may choose to modify the default file to fit
your needs, or you may want to write it from scratch (don't worry, it's really
not that difficult). The basic syntax for the menu XML is as follows:
Code Listing 2.6: Editing the menu.xml file
<?xml version="1.0" encoding="UTF-8"?>
<separator label="NAME_OF_SEPARATOR" />
<menu id="IDENTIFIER" label="NAME_OF_MENU">
The above example will work for any applications that launch with standard
options in their own windows, but what if you need to append options to
the program at launch time? That is no problem either, but the syntax of
the menu item is slightly different.
Code Listing 2.7: Editing the menu.xml file
<?xml version="1.0" encoding="UTF-8"?>
<separator label="NAME_OF_SEPARATOR" />
<menu id="IDENTIFIER" label="NAME_OF_MENU">
<action name="execute"><command>/LOCATION/OF/BINARY --OPTION1 --OPTION2</command></action>
Simply replace anything in CAPS in the above two examples with your information.
Alternatively, you can emerge obmenu, which is a graphical interface
allowing you to create your menus without having to manually edit the
menu.xml file. It is a very small application and offers a
nice amount of customisation without typing any XML.
Openbox theme and behaviour configuration
Aside from being minimalistic and lightweight, Openbox is also surprisingly
customisable and flexible. As a user, you can easily change various settings
related to theme, appearance, window placement, docking, and more. There are two
options for configuring these settings within Openbox. You may either manually
edit ~/.config/openbox/rc.xml, or you may want a GUI to help you
quickly change settings.
If you want to manually edit rc.xml, you simply open up your
favourite text editor and start making changes. You might want to make a backup
of the original file just in case, and store it in a location like
~/.config/openbox/rc.xml.default. There are plenty of comments
within the document itself that should help you with editing. Alternatively, you
may want to look at the Openbox
If manually editing rc.xml doesn't sound like your cup of tea, you
may want to use the GTK+ application to manage your themes and behaviours in
Openbox. The application that you will use is called ObConf, and can be
installed on your system just as easily as was Openbox itself.
Code Listing 2.8: Installing ObConf
# emerge obconf
You can then open the configurator by typing obconf in your terminal.
Next, you can go and add an entry for ObConf into your menu.xml so
it will show up in your Openbox menu. If the "editing the menu.xml file" code
listing above seemed too vague to be helpful, we'll use ObConf as an example of
a menu entry:
Code Listing 2.9: Editing the menu.xml file
<?xml version="1.0" encoding="UTF-8"?>
<menu id="1" label="Configuration">
<item label="OpenBox Config">
While ObConf is a great GUI tool for editing many behaviour-related settings
for Openbox, it doesn't allow one to manipulate nearly as many settings as
are presented in the rc.xml file itself. If you are having
trouble finding a particular setting which you would like to change, please
consult the Openbox Wiki
for more information.
In recent versions of Openbox (namely >18.104.22.168), one may experience a delay
in the submenu opening. This setting was introduced into the rc.xml file, and
is listed as <submenuShowDelay>100</submenuShowDelay>. Simply
choose a lower number that suits your needs.
As mentioned above, you don't see a whole lot when you issue the startx
command for the first time after installing Openbox. In addition to customising
your menus and changing the behaviour of the window manager, you will probably
want to have some programs automatically start with your Openbox session. There
is an easily-editable autostart.sh script that allows you to do
just that. Just like with the menu.xml file, there are two
different locations of the autostart.sh script--the system-wide
(/etc/xdg/openbox/autostart.sh), and the user-defined
In the default autostart.sh, you will notice a bunch of lines
calling for programs like the gnome-settings-daemon, XDG, and others. These
lines will generate errors upon logout if you don't have the programs installed
and configured. The easiest thing to do when getting started with Openbox is to
just comment out these lines by using the # symbol.
Code Listing 2.10: Commenting out lines in autostart.sh
# Run XDG autostart things. By default don't run anything desktop-specific
# if which /usr/lib/openbox/xdg-autostart >/dev/null; then
# /usr/lib/openbox/xdg-autostart $DESKTOP_ENV
In the above example, the comment symbol (#) was added before each line. The
commenting method is preferred to just deleting the lines because you may want
to add support for some of those startup items at a later time. Thus, leaving
the default lines in place could ease that process.
Adding your own programs to the autostart.sh script is as easy as
writing in the program name for many applications. For instance, if you have
lightweight system monitor) installed, and want it to start automatically with
your Openbox session, you simply add the following line to your
Code Listing 2.11: Adding Conky to your autostart.sh
The ampersand (&) after the command allows that application to load up in
the background. You will most likely want to load all the applications in your
autostart.sh script in the background because doing so will let
Openbox and other programs load without the previous one finishing.
Many applications depend on the PolKit authentication
framework. You may need a PolKit agent, such as polkit-gnome, running
in your Openbox session.
First, install the agent:
Code Listing 2.12: Installing PolKit
# emerge polkit-gnome
Now configure PolKit to start automatically when you login to Openbox. Add
the following line to ~/.config/openbox/autostart (for a single
user) or /etc/xdg/openbox/autostart.sh (for all users):
Code Listing 2.13: Start PolKit automatically
sleep 1 && /usr/libexec/polkit-gnome-authentication-agent-1 &
Setting the background
Some things that you might take for granted in bigger desktop environments are
not included by default in Openbox. One such thing is setting your desktop
background. In order to place an image as your wallpaper, you will need to
emerge a program like feh or nitrogen.
feh is a simple image viewer that can also set the background, and
it can easily be put into the autostart script. Once you have emerged
feh, you can issue the following command to set the background:
Code Listing 2.14: Using feh to set the background image
$ feh --bg-scale /path/to/image.jpg
Once you have set the background manually, a file called .fehbg
will be created in your home directory. This file simply contains the above
command that you just entered in the terminal, and is automatically updated
when you issue a different background command. Now, to set your background
automatically upon login, you can add the following line to your
Code Listing 2.15: Using feh to set the background image
source $HOME/.fehbg &
If you don't particularly care for the idea of having to issue a command in the
terminal in order to set your background, you can alternatively use
nitrogen. It will allow you to set a folder for your background images,
view thumbnails of those images, and fit, stretch, or tile them to your
Installing nitrogen and getting it into your Openbox menu requires a few
more steps than are readily apparent. First, you need to emerge nitrogen.
Second, you need to run nitrogen with your backgrounds folder appended:
Code Listing 2.16: Starting nitrogen with your image folder
$ nitrogen /path/to/your/backgrounds/folder
Third, you can set your background image, but it will not be there after you
logout. Just as with feh, you need to restore your background by editing
your autostart.sh script to have the following line:
Code Listing 2.17: Restoring your background with nitrogen
nitrogen --restore &
This will cause nitrogen to load automatically when you start your Openbox
session, and that can lead to a slightly slower load time than using feh.
Programs to use with Openbox
The following is a list of some programs which you might want to use within your
Openbox environment. While the list contains numerous terminal emulators, file
managers, panels, and more, it should by no means be considered exhaustive. If
none of the programs listed fit your needs, please check the appropriate
categories in Portage for more options.
is the default terminal emulator for LXDE. It is very lightweight, and based
on VTE. While EvilVTE offers many more customisation options (including
transparency), LXterminal has a graphical interface for some of the more
common options (font, colors, et cetera).
an extremely lightweight terminal emulator based on (you guessed it) VTE. It
supports tabs, multiple encodings, as well as an easy and extensible
is a multi-tabbed rxvt clone with XFT, transparent background and CJK
support. It also features session support for each tab.
supports transparency and backwards compatibility with rxvt. It was
originally designed for the AfterStep window manager, but easily integrates
with other environments.
is a terminal based on vt102 and designed to be a more feature-rich
replacement for xterm.
is a clone of rxvt that supports Unicode, daemons, embedded perl, and
multiple fonts simultaneously.
is the VTE-based default for the Xfce desktop environment, so it does
require some Xfce libraries to run. However, it is still fairly speedy, and
supports transparency and is easily customised.
the lightweight filemanager from LXDE. It supports tabbed browsing, drag and
drop, thumbnails for images, bookmarks, volume management, searching, and
more. It also provides supports for managing the desktop background and
drawing desktop icons (both optionally).
is the standard file manager from Xfce. It features a bulk renamer,
user-customisable actions, and an extension framework, along with many
optional plugins, such as media tag editing. It depends on several Xfce
libraries, but it's still slimmed down compared to other file managers like
Nautilus (from GNOME), and Konqueror (from KDE).
is the powerful file manager from the GNOME desktop environment. It features
volume management, thumbnails for images, searching, and some system
configuration. As it depends on many of the GNOME libraries for proper
function, it can seem a bit heavy compared to some of the other file
(no relation to this glorious Linux distribution) is a two-pane style file
manager. It is incredibly lightweight, but lacks a some features now
prominent in modern file managers. It should definitely be considered for
older hardware, or if you are wanting a barebones setup.
another file manager in the vein of Midnight Commander. It features a
two-pane window. As with the Gentoo file manager (listed above), it is
barebones and does not include many features prevalent in newer file
managers. However, it also offers a few features not found in other file
managers, such as a built-in commandline in a separate pane.
Though PCManFM is
mainly a file manager, it also gives you the option to manage the desktop
background (instead of using feh or nitrogen) and draw
a simple program used to draw desktop icons. It supports shadowed and
anti-aliased fonts, PNG images, "snap-to-grid" placement, and changing the
Tint2 is a simple,
lightweight panel and taskbar. It supports color, transparency, a clock,
drag and drop between virtual desktops, a system tray, and comes with a
battery monitor. You can even add a button to display the applications menu
from your window manager.
an easily customised panel written in Python and C. It features
transparency, shading, tinting, location and layout configuration, font
type, autohiding, application launcher, clock, and more.
the default panel and taskbar from LXDE. It features a launcher, menu,
clock, and a GUI-based configurator. It is feature-rich while depending on
very few packages, making it a good choice for a lean system.
is the default panel from the Xfce desktop environment. It supports
application launchers, detachable menus, a pager, tasklist, clock, applets,
and more. It does, however, require a few of the Xfce libraries which are
not dependencies of some other panels.
a simple, extremely lightweight panel that supports window lists, launchers,
a clock, and a few other goodies. It's not the most featureful panel, and it
can be cumbersome to configure, but it needs only GTK+ to run.
Pagers and systrays
is an EWMH-compliant pager that integrates nicely into any of the *box
environments. It is not as obtrusive, and is much more readily customisable
than many of the other available pagers.
a desktop pager that was originally written for BlackBox, but works nicely
with Openbox as well. It does have some BlackBox dependencies though.
the system tray that is made especially for Openbox. It has no extra
dependencies, and gives you the ability to view and use tray icons for
supported GTK and QT-based applications.
is a system tray that was modified from the FBpanel code, and is often used
with FVWM. One of its perks is that it supports transparency.
LXsession is the stripped down session manager from LXDE. It is
designed to remember applications that the user was running at the last
logout, and to automatically restart those programs. It also supports the
Xfce4-session is the session manager from, you guessed it, Xfce. It
is capable of saving several sessions, and provides methods for logging out,
rebooting, and suspending your computer. It does, however, have many Xfce
is a GUI application allowing you to customise the Openbox window manager
without manually editing ~/.config/openbox/rc.conf.
is a GTK theme and icon configurator used with LXDE. It provides a nice
graphical interface for setting the theme and icons, while depending on very
few extra libraries.
is a simple application allowing for easier switching of GTK themes and your
font. Currently, it does not allow for the switching of icon themes.
is another simple application that lets you change your GTK theme.
is a lightweight system monitor that can display over 250 objects, including
date and time, CPU usage, memory usage, IMAP/POP3 email, top processes,
hardware sensor data, and even info from your music player. It is highly
customisable both in appearance and data display. We also have a Conky configuration guide available.
is a simple text editor. It is very lightweight, but includes features like
codeset options, and the ability to undo/redo without limits.
feh is a
simple image viewer that runs from the terminal, but it also has many other
features. It can display a slideshow of images, create an index print,
dynamically zoom, and set the desktop background (detailed instructions
is a GUI-based image viewer. Though it has more dependencies than
feh, it is incredibly quick to load and run.
the Simple Login Manager, which allows you to login to your Openbox session
via a graphical interface instead of the terminal. It has very few
dependencies, and supports many themes, but should not be used on machines
that require remote logins.
Openbox inside desktop environments
If installing each component of a working environment sounds like a little
too much customisation, but you still want the flexibility of Openbox,
you may want to look into a desktop environment that uses Openbox as its default
window manager. That environment is LXDE,
the Lightweight X Desktop Environment. Designed to require even fewer system
resources than Xfce, it is built around Openbox.
Openbox inside GNOME
If you already have a GNOME environment installed, you may just want to replace
the Metacity window manager with Openbox. Fortunately, this is quite a simple
task! You will need to fire up your favourite editor, open your
~/.xinitrc file, and put the following command inside it:
Code Listing 4.1: Adding an Openbox-GNOME session to your .xinitrc
If you use GDM or another graphical login manager, you will see a new
"GNOME/Openbox" option in your session menu. You can simply select that option
instead of manually editing your ~/.xinitrc.
Openbox inside KDE
Say you have KDE installed and like it, but you want more flexibility with your
window management than KWin offers. You can use Openbox as your window manager
inside of KDE by simply editing your ~/.xinitrc file, and
replacing your current exec command with the following:
Code Listing 4.2: Adding an Openbox-KDE session to your .xinitrc
Now when you issue startx you will see KDE, but instead of KWin, you
will have the customisability of the Openbox window manager.
If you use KDM or another graphic login manager, you will see a new
"KDE/Openbox" option in your session menu. You can simply select that option
instead of manually editing your ~/.xinitrc.
This method of using Openbox with KDE has been tested with the KDE 3.x
releases. While it seems highly likely that it will work with the KDE 4.x
series, it has not been thoroughly tested as of yet.
Openbox inside Xfce
If you use Xfce4 and would like to replace xfwm4 with Openbox, you will need to
go about it a little differently than with KDE or GNOME. First, you need to
start your normal Xfce session, and open up a terminal. From the terminal,
issue the following command:
Code Listing 4.3: Killing xfwm4 and replacing it with Openbox
$ killall xfwm4 ; openbox & exit
Second, you need to exit out of your Xfce session, and make sure to tick the
checkbox that says "Save session for future login." This will keep Openbox as
your default window manager. Third, you will notice that you can't logout
properly when using the default menu action. To fix this problem, open up your
menu.xml, and locate this line:
Code Listing 4.4: Finding the exit action in menu.xml
Change it to this:
Code Listing 4.5: Replacing the exit action in menu.xml
With Xfce4, the root-menu provided by Xfdesktop will be used instead of the
While this document will easily take you through the inital installation and
customisation of Openbox, it is by no means the only reference on the topic.
There are several other resources that will aid you in creating your perfect
Openbox setup. Some of them are listed below:
On The Official Openbox website
you will find more detailed information regarding theming, creating menus
(including pipe menus), autostart scripting, and much more. This site also
has information regarding new releases, upgrades, and instructions on how
you can contribute to development.
Guide to Openbox blog contains a plethora of information about
switching GTK+ themes, setting up keybindings, desktop effects, and other
programs to use in conjunction with Openbox. Though the tutorial was
originally written for use with Ubuntu, everything is applicable to Gentoo
(and other Linux distributions for that matter).
Box-Look provides numerous
themes, icons, wallpapers, fonts, and tools to be used with Openbox (as well
as the other *box window managers like Fluxbox, Blackbox, PekWM, etc.)
The contents of this document, unless otherwise expressly stated, are licensed under the CC-BY-SA-2.5 license. The Gentoo Name and Logo Usage Guidelines apply.
Page updated December 29, 2012
This guide shows you how to install the Openbox window manager, and references
many potential programs to be used in conjunction with an Openbox session.
Donate to support our development efforts.