From Openbox

Jump to: navigation, search

Menus are not read out of the rc.xml configuration file, but rather out of files specified in the rc.xml. In the default configuration, the menu.xml file is used for all of the menus.

The menu.xml file is located in ~/.config/openbox/menu.xml or in the system-wide /etc/xdg/openbox/menu.xml.


Static menus


A menu file must be entirely enclosed within <openbox_menu> tags, such as:

<openbox_menu> stuff here...

Inside these tags, menus are specified as follows:

<menu id="ID" label="TITLE">
  <!-- this is a menu item, such as a program -->
  <item label="LABEL">

  <!-- this is a menu header -->
  <separator label="La la" />

  <!-- this links to a sub menu -->
  <menu id="ID" />

  <!-- this is a small line separator -->
  <separator />

  <!-- this also links to a sub menu, which is defined inline -->
  <menu id="ID" label="TITLE">
    <item label="LABEL">

  <separator />

  <item label="LABEL">

The syntax example above shows how to put entries into a menu (with <item>), and two methods to add submenus to a menu (with <menu>). It also shows how to put menu headers and separators (with <separator>) into the menu to group items together without submenus.


Each menu must be given an ID which is a unique identifier for the menu. This ID is used to refer to the menu in a ShowMenu action.


The TITLE of the menu is shown when you link to the menu as a submenu. The TITLE will appear in its parent menu.


The LABEL in an <item> tag is the visible name of the menu item. In the <separator> tag, the LABEL transforms the separator from a small horizontal line to a menu header with the given text in it.

Specifying menu shortcuts

The first character in the label is used for a keyboard shortcut to directly use the menu item. This can be overridden by using the _ character in front of the character you wish to use for the shortcut. For example, The _Shortcut would make S the shortcut key for this menu item. If you want a _ character to appear in the string, you can use two underscores together, such as in An __ Underscore.


The ACTIONS are 0 or more actions which are executed in order when you select the menu item. Typically, in menus, these are Execute actions, which run commands.

Pipe menus

Pipe menus are dynamic menus, built on-the-fly from scripts. These are referred to as "Pipe menus" since the script's output is piped back to Openbox and used for the menu. There are a number of pipe menus written by various people available through the Pipe menus page.

A pipe menu can be created by placing the following into a menu file, such as menu.xml:

<menu id="ID" label="TITLE" execute="COMMAND" />

Thereafter the pipe menu can be referenced just like any other menu.


The COMMAND is the script to be executed, which will create the pipe menu for Openbox. The output from this command is parsed and turned into the menu. The output from the script should be a menu, something like:

  <item label="LABEL">

When writing your own pipe menus, make sure to escape xml special characters such as &, etc...

The Debian menu

Source installs or prepackaged .debs from will not configure your setup to show the Debian menu. There are a few simple steps to get it working.

If you have already installed openbox with a working Debian menu

Add this line to your ~/.config/openbox/menu.xml (if it isn't there, copy it from /etc/xdg/openbox/menu.xml):

 <menu id="Debian" />

(NB : on Debian SID, this shoud be <menu id="/Debian" />)

You should place the line where you would like it to appear in the root menu. Location matters!

Add one of these lines to your ~/.config/openbox/rc.xml between the <menu> and </menu> tags, before the entry <file>menu.xml</file> tags:


The second line allows you to copy the debian-menu.xml file from /var/lib/openbox to your local ~/.config/openbox, where it becomes static (command update-menus will not affect it). You can then edit it by hand and your changes will be permanent.

That's all you should have to do, though it's a good idea to run update-menus as root every now and then if you don't have a cron job assigned. It refreshes the list of currently installed apps.

Then choose reconfigure on your root menu and you should get a Debian submenu within the root menu.

If you haven't had a working debian menu

This is a little trickier, but no big deal.

Then there's this little humdinger: you'll need to get a copy of an executable script named "openbox" and copy it to /etc/menu-methods (The script actually creates the Debian menu when you run "update-menus.")

Method 1:

The easiest way is to install an official debian openbox using apt, aptitude or synaptic. This will normally ensure that you have all the packages required to create and use the Debian menu.

After installation copy the script (from /etc/menu-methods) in a known directory (your home directory will fine), then uninstall the offical openbox (with apt, aptitude or synaptic).

Then, copy the script back to /etc/menu-methods and finally, issue the command update-menus as root.

Method 2:

If you don't want to do that, download an official Openbox package (.deb) from, create a dummy directory in /tmp and type the command
dpkg-deb -x <officialopenbox.deb> </tmp/dummy_dir>

This will unpack a mini-filesystem that includes the script you need in /tmp/dummy_dir/etc/menu-methods. Set its execution permissions, copy the script to /etc and issue the command update-menus as root. The latter command will create the file /var/lib/openbox/debian-menu.xml.

To set the execution permissions type:
chmod ug+x /tmp/dummy_dir/etc/openbox

The reason to create a dummy directory is that running the dpkg-deb -x command will change the ownership of the directory to root. These could become a bit of a problem later; putting it in a subdirectory of /tmp makes that issue, inoffensive.

Also, you should make sure you have the following packages installed before running update-menus:

  • menu
  • menu-xdg

Now follow the instructions in "If you have already installed openbox with a working Debian menu" above.

Personal tools