Gentoo Wiki


Desktop environments

Lightweight desktop environments

Window managers

Compositing window managers


Openbox with aterm, gkrellm, torsmo, idesk, and pypanel (desktop from Ninjai)
Openbox with aterm, gkrellm, torsmo, idesk, and pypanel (desktop from Ninjai)
Openbox with Eterm and conky on Openbox-3.3-rc2. By User:Chronos
Openbox with Eterm and conky on Openbox-3.3-rc2. By User:Chronos


What is Openbox?

Openbox is a fast, lightweight and highly configurable X11 window manager with extensive standards support. It is released under the GNU GPL. It can act as a full-featured standalone window manager or be used as a drop-in window manager for desktop environments like Gnome or KDE.

Openbox 2 and earlier versions were based on the Blackbox 0.65.0 code base, written in C++, with no dependencies other than X11. Openbox 3 has been completely rewritten in C and is not based upon any existing code base. It depends on libxft2 and X11.

View the official website here:


Openbox has several advantageous features, as compared to other window managers:

Installing and Configuring Openbox

As root run emerge openbox

For additional themes, emerge commonbox-styles.

Getting started guide

This wiki section is outdated. See the Openbox getting started guide for how to run Openbox 3.4.

Openbox with Gnome

The default window manager for the GNOME environment is metacity. To switch from metacity to Openbox, run the following command as the user you want to run openbox:

openbox --replace

Choose Save your Session next time you log out so that Openbox will be started for you when you log in again.

Since GNOME 2.4, gnome-panel no longer manages its own key bindings and requires that the window manager provide its own key bindings for showing the Main Menu and Run dialog. Openbox does this through gnome-panel-control, which can be used in keybindings to access the gnome-panel. Use the --main-menu option to display gnome-panel's menu, and the --run-dialog to display the Run dialog.

Openbox with KDE

The default window manager for the KDE environment is kwin. To switch from kwin to Openbox, set the following environment variable in your startup scripts:

export KDEWM=openbox

Openbox will now be used in kwin's place.

The current release of KDE is still using a non-standard, deprecated protocol for its system tray. This protocol requires interaction from the window manager. Openbox includes the kdetrayproxy application, which acts as a go-between between Openbox and KDE. Once you run kdetrayproxy, KDE system tray apps will work with window managers that don't support KDE's protocol.

To run kdetrayproxy before running KDE, make a startup script or modify xinitrc as shown:

File: ~/.xinitrc
# Startup stuff for X

# Make openbox the KDE window manager
export KDEWM=openbox

# Make KDE system tray apps work
kdetrayproxy &

# Start the KDE environment

Standalone Openbox

If you want Openbox as a standalone window manager, run openbox or modify $HOME/.xinitrc or /etc/X11/xinit/xinitrc as such:

File: ~/.xinitrc or /etc/X11/xinit/xinitrc
#Startup stuff for X
exec openbox-session

If you run X via a display manager (xdm, gdm, kdm, ...)

You may consult the documentation for your specific display manager regarding adding entries to it. Alternately, you can edit a $HOME/.xsession file. The file is a shell script and can be made identical to the .xinitrc example above. With this method, you would choose "default" as the login target in your display manager.

gdm - if you have gdm installed, when you emerge openbox, portage will install /usr/share/xsessions/openbox.desktop

kdm -- kdm also uses the /usr/share/xsessions/openbox.desktop to give you a nice graphical selection in the sessions menu. But if you want other programs to run at startup (like the background scripts listed below) you need to put all the commands in the ~/.xsession file. Be sure to end with exec openbox and make it executable, for example:

File: ~/.xsession

gkrellm2 &
xscreensaver -nosplash
exec openbox

This starts the gkrellm monitoring program, the xscreensaver dameon and finally Openbox. Now you can select the "Custom" session at the kdm/gdm login prompt to execute the ~/.xsession file.

There is another method to start other programs at startup not using the ~/.xsession (for example because you want to have two different Openbox session that start different applications):

Write a script that looks like the ~/.xsession above, save it (e.g. to /usr/local/bin/startopenbox) and make it executable.

Now edit /usr/share/xsessions/openbox.desktop (or create a new *.desktop):

File: /usr/share/xsessions/openbox.desktop
[Desktop Entry]
Comment=Openbox and other apps
Exec=startopenbox              # <- this should be the name/path of/to your new script

Instead of selecting the "Custom" session you can now use the "Openbox" session (or whatever you named it).

Basic Introduction

When Openbox first starts, it'll look like nothing is there. Right click, and there's your menu. At this point, you may be a little shocked by how bare it looks. Don't worry, that will soon be fixed! (Assuming you want to "fix" it, of course...)

Also, Openbox doesn't come with a panel (a bar down the bottom), but instead uses a system of right clicking on the desktop. A panel may be added after configuration. If you rightclick on the desktop now, you should see some sample entries, such as Quake 3, Mozilla etc etc...

Configuring Openbox

Openbox is easily configurable, as all the files it has are in simple to grasp XML. You can either edit the files manually, or get a tool called Obconf to do (the majority) of it for you.


Obconf is a configurator for Openbox, and lets you control Appearance, Behavior, Desktops and Docking. Simple emerge obconf and you have it.

It doesn't have the ability to modify menus, or for that matter anything other than the largest options. You'll have to go the XML route to configure the other options.

You need to emerge version 1.6 if you plan to install it.

GTK Applications

If you don't have a full-blown GNOME installation on your system and you want greater control of your GTK applications, you can use the .gtkrc-2.0 file. You can set things such as the theme name, icon theme, and specify some font settings among other things.

File: ~/.gtkrc-2.0
gtk-icon-theme-name = "Etiquette"
gtk-theme-name = "Clearlooks"
gtk-font-name = "Bitstream Vera Sans 8"

style "user-font"
        font_name = "Bitstream Vera Sans 8"

widget_class "*" style "user-font"

The icon and theme name are specified based on the given name of that particular theme. There are two font settings purely for backwards compatibility with certain applications, but some applications still partially ignore these settings. For instance, Mozilla Firefox 1.0.7 will still use larger fonts in rendered pages, but the application font itself will use the font that you specified.

Note: If you use Obconf with this custom file, Obconf will overwrite this rather than appending to it.

Generate Menu Entries

The Openbox menu contains (out of the box) only the most widely distributed applications. You can use the menuMaker (emerge menumaker) tool to generate the menu configuration file, like so:
mmaker OpenBox3

This utility scans for applications it knows about, and it knows a lot!

There is also another utility which you can use, it's called Denu and it's in portage.

Manual Configuration

For more information, goto Openbox Configuration Page

Open a text editor, such as nano, vim, emacs, nedit, etc. and head to these directories:

  1. $HOME/.config/openbox/ - for specific users
  2. /etc/xdg/openbox/ - for the whole system, though if Openbox finds one in ~ first, that's the default

The main two files you will find there are rc.xml and menu.xml

An example menu.xml file:

File: menu.xml
 <?xml version="1.0" encoding="UTF-8"?>

 <openbox_menu xmlns=""

 <menu id="appall-menu" label="Apps">
 <menu id="apps-menu" label="Applications">
   <item label="Firefox">
     <action name="Execute"><execute>firefox</execute></action>
     <item label="Links">
     <action name="Execute"><execute>links -g</execute></action>
   <item label="AMSN">
     <action name="Execute"><execute>amsn</execute></action>
   <item label="Blender CVS">
     <action name="Execute"><execute>/home/blender/blender/blender -w</execute></action>
   <item label="XChat-2">
     <action name="Execute"><execute>xchat-2</execute></action>
   <item label="Torsmo">
     <action name="Execute"><execute>torsmo</execute></action>
   <item label="Scrot">
     <action name="Execute"><execute> scrot $f /home/smerity/ping.png </execute></action>
 <menu id="games-menu" label="Games">
   <item label="Frozen Bubble">
     <action name="Execute"><execute>/usr/games/bin/frozen-bubble</execute></action>
   <item label="FreeDroid">
     <action name="Execute"><execute>/usr/games/bin/freedroid</execute></action>
   <item label="Amor">
     <action name="Execute"><execute>/usr/kde/3.3/bin/amor</execute></action>
   <item label="XBill">
     <action name="Execute"><execute>/usr/games/bin/xbill</execute></action>
   <item label="SuperTux">
     <action name="Execute"><execute>/usr/games/bin/supertux</execute></action>
   <item label="WMFortune">
     <action name="Execute"><execute>wmfortune -s 19999</execute></action>
 <menu id="term-menu" label="Terminals">
  <item label="Smerterm">
     <action name="Execute"><execute>aterm -bg LightBlue -tr -tint LightBlue -sh 70 -fade 70 -bgtype scale -name
 Smerity -ls -fg grey +st</execute></action>
   <item label="Aterm">
     <action name="Execute"><execute>aterm</execute></action>
   <item label="Xterm">
     <action name="Execute"><execute>xterm</execute></action>
   <item label="Rox FM">
     <action name="Execute"><execute>rox /root/</execute></action>

 <menu id="kde-menu" label="KDE">
   <item label="Kicker">
     <action name="Execute"><execute>kicker</execute></action>
   <item label="KDesktop">
     <action name="Execute"><execute>kdesktop</execute></action>
   <item label="KDE System Guard">
     <action name="Execute"><execute>ksysguard</execute></action>

 <menu id="open-menu" label="OpenBox Apps">
   <item label="ObConf">
     <action name="Execute"><execute>obconf</execute></action>
   <item label="Reconfigure">
     <action name="Reconfigure" />
   <separator />
   <item label="Feh">
     <action name="Execute"><execute>feh --bg-scale /home/mountain_man2.jpg</execute></action>
   <item label="Menu.xml">
     <action name="Execute"><execute>nedit /etc/xdg/openbox/menu.xml</execute></action>
   <item label="Rc.xml">
     <action name="Execute"><execute>nedit /etc/xdg/openbox/rc.xml</execute></action>
   <separator />
   <item label="Gkrellm">
     <action name="Execute"><execute>gkrellm2</execute></action>
   <menu id="kdm-menu" />

 <menu id="root-menu" label="Openbox 3">
   <item label="Smerterm">
     <action name="Execute"><execute>aterm -bg LightBlue -tr -tint LightBlue -sh 70 -fade 70 -bgtype scale -name Smerity -ls -fg grey +st</execute></action></item>
   <item label="Konqueror">
     <action name="Execute"><execute>/usr/kde/3.3/bin/konqueror / </execute></action>
   <menu id="appall-menu" />
   <menu id="open-menu" />
   <separator />
   <menu id="client-list-menu" />
   <separator />
   <item label="Nedit">
     <action name="Execute"><execute>nedit</execute></action>
   <item label="Notes">
     <action name="Execute"><execute>nedit /home/Notes</execute></action>
   <separator />
   <item label="Reboot">
     <action name="Execute"><execute>reboot</execute></action>
   <item label="Exit">
     <action name="Exit" />


As you can see, this file can get big very fast. If you are a Vim user you can tell Vim to fold the different sections so that you can get a better idea of the overall picture. With xml folding enabled the menu file given above looks like:

File: menu.xml
 <?xml version="1.0" encoding="UTF-8"?>

 <openbox_menu xmlns=""

+--- 60 lines: <menu id="appall-menu" label="Apps">---------------------------------

+--- 11 lines: <menu id="kde-menu" label="KDE">-------------------------------------

+--- 23 lines: <menu id="open-menu" label="OpenBox Apps">---------------------------

+--- 25 lines: <menu id="root-menu" label="Openbox 3">------------------------------


To look at the contents of the fold simply put your cursor on the desired line and type "zo" (fold open). To close it again type "zc" (fold close).

To enable folding for xml files create a file named ~/.vim/after/syntax/xml.vim (creating directories as needed) with the following contents:

File: xml.vim
syn sync fromstart
set foldmethod=syntax
"This variable sets the fold level that you start in
set foldlevel=1
"This variable tells vim depth of nesting to use
set foldnestmax=3
"This sets the color of the folds to distinguish them from
"the rest of the text
highlight Folded ctermbg=DarkGrey ctermfg=DarkCyan

Then add "let g:xml_syntax_folding = 1" to your ~/.vimrc file. Now open up the menu.xml to test it out.

Pipe Menus

One of the more useful features of Openbox is the ability to pipe scripts into a menu. An entry in your menu.xml might look like this:

File: menu.xml
 <menu id="pipemenu" label="Piped Script" execute="~/obmenuscript" />

There are many sites dedicated to Openbox scripts; here is a collection of most of them. If you feel like writing your own, it is very simple. Simply write a script or program in whatever language you want and make sure it outputs a properly formatted menu (follows the general rules for menu.xml) to standard output. Make sure that errors are also properly formatted entries in the menu.

Panels, Desktops and Backgrounds




feh - A lightweight image viewer, supporting many file formats. This can also set the background. It can be run from the command line:

feh --bg-scale ~/your/background.jpg

Feh stores its background command in ~/.fehbg, making it simple to set your desktop when X starts up:~/.xinitrc:

File: ~/.xinitrc
eval `cat $HOME/.fehbg` &
exec openbox-session

You can only set an image as a background with feh, not a color or gradient.

xsetbg - Comes with X, but doesn't support many formats and can be painful to set up. It does not do well with (xcompmgr), if ever you want to use it.

Another option is ImageMagick. It's also easy:

display -dispose Background -window root ~/your/background.jpg

It is also possible to Make your background rotate with feh.

Last modified: Sat, 06 Sep 2008 07:35:00 +0000 Hits: 85,829