Build an Openbox Application Menu with obamenu

obamenu scans your installed .desktop files and hands Openbox a ready-made Applications menu, no hand-written XML required. By the end, that menu will be generated fresh every time you open it, live in your home directory, and you will know exactly where to look when an application or icon goes missing.

Allow about 15 minutes for a first setup. You need a working Openbox session, a text editor, and permission to read the application directories. Nothing here needs elevated privileges except the optional system-wide install step.

1. Confirm the installed behaviour

The machine used for this guide runs Ubuntu's openbox 3.6.1-12build5, whose obamenu script identifies itself as version 1.1.7. Check your own package before trusting these defaults:

dpkg-query -W -f='${Package} ${Version}\n' openbox
command -v obamenu
head -n 8 "$(command -v obamenu)"

obamenu takes no command-line options or parameters. Running it prints an Openbox pipe-menu document on standard output:

obamenu | sed -n '1,12p'

On this installation the output opens with an XML declaration and an <openbox_pipe_menu> root, followed by menus such as Development, Graphics, Internet, System and Utilities wherever matching applications exist. Empty categories are simply omitted. Your list will look different because it is built from the .desktop files actually present on your system.

2. Make a user-owned copy

The configuration lives as a short section inside the Python script itself, not a separate config file. Do not edit /usr/bin/obamenu in place unless you deliberately want a package-managed file changed, a package upgrade can overwrite it without warning. Keep a reversible, user-owned copy instead:

mkdir -p "$HOME/bin"
install -m 755 "$(command -v obamenu)" "$HOME/bin/obamenu"
cp "$HOME/bin/obamenu" "$HOME/bin/obamenu.bak"
editor "$HOME/bin/obamenu"

Near the top of the copy you will find user configuration like this. Adjust the values to suit your machine rather than copying the sample terminal name blindly:

applications_dirs = ("/usr/share/applications", )
image_dir_base = "/usr/share"
icon_Theme = "Humanity"
image_cat_prefix = "applications-"
application_groups = ("Office", "Development", "Graphics", "Internet",
                      "Games", "System", "Multimedia", "Utilities", "Settings")
group_aliases = {"Audio":"Multimedia", "AudioVideo":"Multimedia",
                 "Network":"Internet", "Game":"Games", "Utility":"Utilities",
                 "GTK":"", "GNOME":""}
ignoreList = ("evince-previewer", "feh")
terminal_string = "x-terminal-emulator -e"
simpleOBheader = False

• applications_dirs is a tuple of directories to scan. Add a second one with a trailing comma, for example ("/usr/share/applications", "/opt/example/share/applications", ). It only reads the directory entries given, it never recurses into subdirectories on its own.
• application_groups controls which categories appear at all, and in what order. Leave a category out and it produces no menu entry.
• group_aliases maps a category name found in a desktop file onto one of your chosen groups. Map it to an empty string to hide it, useful for noisy categories, but a careless alias can make an application seem to vanish.
• ignoreList holds desktop file names without the .desktop suffix. The script checks whether each name occurs anywhere in the file path, so pick something distinctive.
• terminal_string gets prepended whenever a desktop file declares Terminal=true. It must be a command that accepts the application command straight after its own terminal option.

Icons are a separate concern. Application icons are looked up under /usr/share/pixmaps, category icons under /usr/share/icons/<theme>/categories/24/. A desktop file naming an icon stored elsewhere still gets a working menu entry, just with no icon. The manpage's own advice is a symbolic link in the pixmaps directory, rather than teaching the generator to search an entire icon tree. Creating that link needs sudo and changes system state, so confirm the target first:

find /usr/share/icons -name 'example.*' -print
ls -l /usr/share/pixmaps/example.*

3. Test the customised generator

Save the script, then run it directly. Redirecting to a temporary file makes the XML easy to inspect without touching Openbox:

"$HOME/bin/obamenu" > "$HOME/obamenu-test.xml"
head -n 3 "$HOME/obamenu-test.xml"
grep -E '^<(menu|item)\b' "$HOME/obamenu-test.xml" | head

sed -n '1,100p' /usr/share/applications/example.desktop

Look for Type=Application, a Categories= line matching one of your groups or aliases, and an Exec= line. obamenu strips a trailing desktop-file field placeholder such as %f from the command, but it does not turn arbitrary shell syntax into a script, so keep commands simple and test unusual launchers on their own.

4. Attach it to Openbox

Openbox reads menus from its configured menu file, normally $HOME/.config/openbox/menu.xml. Back it up before editing: this is a reversible change, but a malformed XML file can leave the menu unavailable until it is restored:

mkdir -p "$HOME/.config/openbox"
cp "$HOME/.config/openbox/menu.xml" "$HOME/.config/openbox/menu.xml.bak"
editor "$HOME/.config/openbox/menu.xml"

Inside an existing <menu>, add a submenu whose execute attribute names the user-owned generator. Use an absolute path so Openbox does not depend on the session's PATH:

<menu id="desktop-app-menu"
      label="Applications"
      execute="/home/REPLACE_WITH_YOUR_LOGIN/bin/obamenu" />

Place that menu inside the top-level menu structure your configuration already uses. Do not paste the generator's own output into menu.xml, the execute attribute tells Openbox to run the command and parse its output as a pipe menu, and the generated document already supplies the pipe-menu root and closing element on its own.

Reload Openbox from its normal menu or your reload shortcut, then open Applications. If it does not show up, run the exact command from the execute attribute in a terminal and confirm it is executable:

test -x "$HOME/bin/obamenu" && echo executable
"$HOME/bin/obamenu" > /tmp/obamenu-output.xml
sed -n '1,8p' /tmp/obamenu-output.xml

cp "$HOME/.config/openbox/menu.xml.bak" "$HOME/.config/openbox/menu.xml"

Common traps

• Expecting flags: obamenu accepts no options. Configuration belongs in the script copy.
• Editing the wrong copy: the menu must execute the path you customised, not necessarily /usr/bin/obamenu.
• Missing categories: categories are case-sensitive strings in the script. An alias to an empty string deliberately hides an application.
• Missing icons: application icon names are not searched across the whole icon theme tree. Check /usr/share/pixmaps and the configured category theme.
• Terminal applications opening wrong: check terminal_string against the desktop file's Terminal=true. The configured terminal command must accept the generated command as-is.
• Stale output: the menu is generated fresh each time Openbox invokes it. Re-run the generator and reload Openbox after changing the script or desktop files.