Difference between revisions of "Openbox"

From ArchWiki
Jump to navigation Jump to search
(a new section detailing Openbox Multihead along with a compatible pager and pytyle)
Line 138: Line 138:
(When terminating Xfdesktop, the above issue with the virtual desktops is no longer a problem.)
(When terminating Xfdesktop, the above issue with the virtual desktops is no longer a problem.)
== Openbox for multihead users ==
While Openbox provides better than average multihead support on its own, a branch called [http://aur.archlinux.org/packages.php?ID=51460 Openbox Multihead] is now available in the AUR that gives multihead users per-monitor desktops. This model is not commonly found in floating window managers, but exists mainly in tiling window managers. It is explained well on the [http://xmonad.org/tour.html#workspace Xmonad web site]. Also, please see [https://github.com/BurntSushi/openbox-multihead/blob/multihead/README.MULTIHEAD README.MULTIHEAD] for a more comprehensive description of the new features and configuration options found in Openbox Multihead.
Openbox Multihead will function like normal Openbox when only a single head is available.
A downside to using Openbox Multihead is that it breaks the EWMH assumption that one and only one desktop is visible at any time. Thus, existing pagers will not work well with it. To remedy this, [http://aur.archlinux.org/packages.php?ID=51536 pager-multihead] can be found in the AUR that is compatible with Openbox Multihead. [http://imgur.com/a/cnZeq#y04nk Screenshots].
Finally, a new version of [http://aur.archlinux.org/packages.php?ID=51626 pytyle] can also be found in the AUR that will work with Openbox Multihead.
Both pytyle3 and pager-multihead will work without Openbox Multihead if only one monitor is active.
== Configuration ==
== Configuration ==

Revision as of 00:52, 18 August 2011

This template has only maintenance purposes. For linking to local translations please use interlanguage links, see Help:i18n#Interlanguage links.

Local languages: Català – Dansk – English – Español – Esperanto – Hrvatski – Indonesia – Italiano – Lietuviškai – Magyar – Nederlands – Norsk Bokmål – Polski – Português – Slovenský – Česky – Ελληνικά – Български – Русский – Српски – Українська – עברית – العربية – ไทย – 日本語 – 正體中文 – 简体中文 – 한국어

External languages (all articles in these languages should be moved to the external wiki): Deutsch – Français – Română – Suomi – Svenska – Tiếng Việt – Türkçe – فارسی

Openbox is a lightweight and highly configurable window manager with extensive standards support. Its features are documented at the official website. This article pertains to installing Openbox under Arch Linux.


Template:Package Official is available from the community repository:

# pacman -S openbox

After installation, you should copy the default configuration files Template:Filename, Template:Filename, Template:Filename, and Template:Filename to Template:Filename:

Note: Do this as a regular user, not as root.
$ mkdir -p ~/.config/openbox
$ cp /etc/xdg/openbox/{rc.xml,menu.xml,autostart,environment} ~/.config/openbox

Template:Filename is the main configuration file. It defines keyboard shortcuts, themes, virtual desktops, and more.

Template:Filename defines the content of the right-click menu. It defines launchers for applications and other shortcuts. See the #Menus section.

Template:Filename is read by openbox-session at startup. It contains the programs that are run at startup. It is typically used to set environment variables, launch panels/docks, set background image or execute other startup scripts. See the Openbox Wiki.

Template:Filename is sourced by openbox-session at startup. It contains environment variables to be set in Openbox's context. Any variables you set here will be visible to Openbox itself and anything you start from its menus.

Upgrading to Openbox 3.5

If you are upgrading to Openbox 3.5 or later from an earlier release, be aware of these changes:

  • There is a new config file called Template:Filename that you should copy from /etc/xdg/openbox to ~/.config/openbox .
  • The config file previously called Template:Filename is now just called Template:Filename. You should rename yours to remove the .sh from the end of the name.
  • Some of the configuration grammar in Template:Filename has changed. While Openbox appears to understand the old options, it would be wise to compare your configuration to the one in /etc/xdg/openbox and look for changes that affect you.

Troubleshooting 3.5

See the Troubleshooting Openbox 3.5 section below.

Openbox as a stand-alone WM

Openbox can be used as a stand-alone window manager (WM). This is usually simpler to install and configure than using Openbox with desktop environments. Running openbox alone may reduce your system's CPU and memory load.

To run Openbox as a stand-alone window manager, append the following to Template:Filename:

exec openbox-session

You may also start Openbox from the command shell (aka: text prompt) using xinit:

$ xinit /usr/bin/openbox-session

If you used another window manager previously (such as Xfwm) and now Openbox won't start after logging out of X, try moving the autostart folder:

mv ~/.config/autostart ~/.config/autostart-bak

Using Consolekit, use this instead:

exec ck-launch-session openbox-session

If you also use polkit and D-Bus (e.g. for auto-mount drivers in Nautilus/Gnome) use:

exec ck-launch-session dbus-launch openbox-session
Note: pyxdg is required for Openbox's xdg-autostart
Note: "dbus-launch" must be placed after "ck-launch-session" or you will experience mounting problems

Openbox as a WM for desktop environments

Openbox can be used as a replacement window manager for full-fledged desktop environments. The method for deploying Openbox depends on the desktop environment.

GNOME 2.24 and 2.26

Create Template:Filename with the following lines:

[Desktop Entry]
# name of loadable control center module
# name we put on the WM spec check window

In gconf, set  Template:Codeline  to  Template:Codeline:

$ gconftool-2 -s -t string /desktop/gnome/session/required_components/windowmanager openbox

Finally, choose GNOME session from the GDM sessions menu.

GNOME 2.26 Redux

If the previous guide for GNOME 2.24 fails:

If, when attempting to log into a "Gnome/Openbox" session -- and it consistently fails to start, try the following. This is one way of achieving your goal of using Openbox as the WM anytime you open a Gnome session:

  1. Log into your Gnome-only session (it should still be using Metacity as its window manager).
  2. Install Openbox if you have not done so already
  3. Navigate your menus to System → Preferences → Startup Applications (possibly named 'Session' in older Gnome versions)
  4. Open Startup Application, select '+ Add' and enter the text shown below. Omit the text after #.
  5. Click the 'Add' button for the data entry window. Make sure the checkbox beside your new entry is selected.
  6. Log out from your Gnome session and log back in
  7. You should now be running openbox as your window manager.
Name:    Openbox Windox Manager          # Can be changed
Command: openbox --replace               # Text should not be removed from this line, but possibly added to it
Comment: Replaces metacity with openbox  # Can be changed

This creates a startup list entry which is executed by Gnome each time the user's session is started.

GNOME 2.22 and prior

  1. If you use GDM, select the "GNOME/Openbox" login option
  2. If you use Template:Codeline, add Template:Codeline to Template:Filename
  3. From the shell:
$ xinit /usr/bin/openbox-gnome-session


  1. If you use KDM, select the "KDE/Openbox" login option
  2. If you use startx, add Template:Codeline to Template:Filename
  3. From the shell:
$ xinit /usr/bin/openbox-kde-session


Log into a normal Xfce4 session. From your terminal, type:

$ killall xfwm4 ; openbox & exit

This kills xfwm4, runs Openbox, and closes the terminal. Log out, being sure to check the "Save session for future logins" box. On your next login, Xfce4 should use Openbox as its WM.

To enable exiting from a session using xfce4-session, edit  Template:Filename.  If the file isn't there, copy it from  Template:Filename.  Look for the following entry:

 <item label="Exit Openbox">
   <action name="Exit">

Change it to:

 <item label="Exit Openbox">
   <action name="Execute">

Otherwise, choosing "Exit" from the root-menu causes Openbox to terminate its execution, leaving you with no window manager.

If you have a problem changing virtual desktops with the mouse wheel skipping over desktops, edit Template:Filename. Move the mouse binds with... actions "DesktopPrevious" and "DesktopNext" from context  Desktop  to the context  Root.  (You may need to create a definition for the Root context as well.)

When using the Openbox root-menu instead of Xfce's menu, you may exit the Xfdesktop with this terminal command:

$ xfdesktop --quit

Xfdesktop manages the wallpaper and desktop icons, requiring you to use other utilities such as ROX for these functions.

(When terminating Xfdesktop, the above issue with the virtual desktops is no longer a problem.)

Openbox for multihead users

While Openbox provides better than average multihead support on its own, a branch called Openbox Multihead is now available in the AUR that gives multihead users per-monitor desktops. This model is not commonly found in floating window managers, but exists mainly in tiling window managers. It is explained well on the Xmonad web site. Also, please see README.MULTIHEAD for a more comprehensive description of the new features and configuration options found in Openbox Multihead.

Openbox Multihead will function like normal Openbox when only a single head is available.

A downside to using Openbox Multihead is that it breaks the EWMH assumption that one and only one desktop is visible at any time. Thus, existing pagers will not work well with it. To remedy this, pager-multihead can be found in the AUR that is compatible with Openbox Multihead. Screenshots.

Finally, a new version of pytyle can also be found in the AUR that will work with Openbox Multihead.

Both pytyle3 and pager-multihead will work without Openbox Multihead if only one monitor is active.


There are several options for configuring Openbox settings:

Manual configuration

To configure Openbox manually, edit the Template:Filename file with a text editor. The file has explanatory comments throughout. See the Help:Configuration openbox wiki for more documentation on editing this file.


ObConf is an Openbox configuration tool. It is used to set most common preferences such as themes, virtual desktops, window properties, and desktop margins. It can be installed with pacman:

# pacman -S obconf

ObConf cannot configure keyboard shortcuts and certain other features. For these features edit Template:Filename manually. Alternatively, you can try Template:Package AUR from the AUR.

Application customization

Openbox allows per-application customizations. This lets you define rules for a given program. For example:

  • Start your web browser on a specific virtual desktop.
  • Open your terminal program with no window decorations (window chrome).
  • Make your bit-torrent client open at a given screen position.

Per-application settings are defined in Template:Filename. Instructions are in the file's comments. More details are found in the Help:Applications openbox wiki.


The default Openbox menu includes a variety of menu items to get you started. Many of these items launch applications you don't want, haven't installed yet, or never intend to install. You'll surely want to customize  Template:Filename  at some point. There are a number of ways to do so.

Manual configuration of menus

You can edit Template:Filename with a text editor. Many of the settings are self-explanatory. The article Help:Menus has extensive details.

Icons in menu

Since version 3.5.0 you can have icons next to your menu entries. To do that :

  1. add <showIcons>yes</showIcons> in the <menu> section of the Template:Filename file
  2. edit the menu entries in Template:Filename and add icons="<path>" like this :
<menu id="apps-menu" label="SomeApp" icon="/home/user/.icons/application.png">

then openbox --reconfigure or openbox --restart if you have troubles updating the menu :)


MenuMaker creates XML menus for several window managers including Openbox. MenuMaker searchs your computer for executable programs and creates a menu file from the result. It can be configured to exclude certain application types (GNOME, KDE, etc) if you desire.

# pacman -S menumaker    #  Install MenuMaker from the repository

Once installed, generate a menu file (named Template:Filename) by running the program.

$ mmaker -v OpenBox3     #  Will not overwrite an existing menu file.
$ mmaker -vf OpenBox3    #  Force option permits overwriting the menu file.
$ mmaker --help          #  See the full set of options for MenuMaker.

MenuMaker creates a comprehensive Template:Filename. You may edit this file by hand or regenerate it after installing software.


Obmenu is a menu editor for Openbox. This GUI application is the best choice for those who dislike editing XML code. Obmenu is available in the community repository:

# pacman -S obmenu

Once installed, run Template:Codeline then add and remove applications as desired.


Openbox-menu uses menu-cache from the LXDE Project to create dynamic menus for Openbox.

Project homepage here: http://mimasgpc.free.fr/openbox-menu_en.html

AUR Package here: http://aur.archlinux.org/packages.php?ID=31605


obm-xdg is a command-line tool that comes with Obmenu. It generates a categorized sub-menu of installed GTK/GNOME applications.

To use obm-xdg with other menus, add the following line to Template:Filename:

<menu execute="obm-xdg" id="xdg-menu" label="xdg"/>

Then add the following line under your 'root-menu' entry where you want to have the menu appear:

<menu id="xdg-menu"/>

To use obm-xdg by itself create Template:Filename and add these lines:

 <menu execute="obm-xdg" id="root-menu" label="apps"/>

Then run Template:Codeline to refresh the Openbox menu. You should now see a sub-menu labeled xdg in your menu.

Note: If you do not have GNOME installed, you need to install package gnome-menus for obm-xdg.

Python-based xdg menu script

This script is found in Fedora's Openbox package. You have only to put the script somewhere and create a menu entry.

Here is the head: latest script

Download from above repository. Place the file into the directory you want.

Open Template:Filename with your text editor and add the following entry. Of course, you can modify the label as you see fit.

<menu id="apps-menu" label="xdg-menu" execute="python2 <path>/xdg-menu"/>

Save the file and run Template:Codeline.

Note: If you do not have GNOME installed, you need to install package gnome-menus for xdg-menu.

Openbox menu generator

Residing in the AUR as obmenugen-bin, Openbox menu generator creates the menu file from *.desktop files. Obmenugen provides a text file which filters (hides) menu items using basic regex.

$ obmenugen               # Create a menu file
$ openbox --reconfigure   # To see the menu you generated

Pipe menus

Like other window managers, Openbox allows for scripts to dynamically build menus (menus on-the-fly). Examples are system monitors, media player controls, or weather monitors. Pipe menu script examples are found in the Openbox:Pipemenus page at Openbox's site.

User Xyne created a pipe menu file browser and user brisbin33 created a pipe menu for scanning and connecting to wireless hot spots (using netcfg). Forum posts for these utilities are here: file browser and here: wifi.

User jnguyen created a pipe menu for managing removable devices using Udisks. The forum post is here: obdevicemenu.

Startup programs

Openbox supports running programs at startup. This is provided by command openbox-session.

Enabling autostart

There are two ways to enable autostart:

  1. When using startx or xinit to begin a session, edit Template:Filename. Change the line that executes openbox to openbox-session.
  2. When using GDM or KDM, selecting an Openbox session automatically runs the autostart script.

Autostart script

Openbox executes a user startup script located at Template:Filename. This script is not created by default. In the absence of a user startup script, openbox executes the system startup script Template:Filename. The system script does not run when the user script is present.

To create a personal startup script, copy the system script to your settings directory Template:Filename and append your commands. This ensures your environment is properly configured.

Full instructions are available from the Help:Autostart article at the Openbox site.

Note: This file used to be called autostart.sh before OpenBox 3.5.0. If you are upgrading, be sure you rename your copy of the file to remove the .sh from the end, or it will stop being read.

Themes and appearance

Template:Box YELLOW

You probably installed a selection of Linux programs that were developed using different toolkits. Configuration settings for a given program may reside in an unexpected location.

For example, the double-click setting used by Geany (an editor/IDE) is set within the file  Template:Filename  not where you might expect in Template:Filename. Some visual aspects of Geany are set by .gtkrc-2.0 as well.

Refer to the supplemental Openbox Themes and Apps for visual theming information.

Openbox themes

Themes control the appearance of windows, titlebars, and buttons. They also control menu appearance and on-screen display (OSD). Additional themes are available from the standard repositories.

# pacman -S openbox-themes

Cursors, icons, wallpaper

Please see Openbox Themes and Apps for information on these GUI customizations.

Recommended programs

Template:Box YELLOW

There is a list of Lightweight Applications in the wiki. Most of these work nicely with Openbox.

Login managers

SLiM is a graphical login manager. It works for standalone Openbox configurations. Refer to the SLiM wiki article for instructions.

Qingy is a light, highly-configurable graphical login manager. It supports login to either text console or X session. Qingy uses DirectFB. Qingy does not start an X session unless you choose a session that uses X Windows. Read the Arch wiki article about Qingy.

Compositing the desktop view

Xcompmgr is a compositing window manager capable of rendering drop shadows, fading, and window transparency for Openbox and other window managers. Note that xcompmgr is no longer being developed. Any problems are unlikely to be fixed. (For example, Xcompmgr has shown a problem with tint2 0.9: systray icons have a tendency to become corrupted.)

Cairo Compmgr is a versatile compositing window manager that uses Cairo for rendering. It is usually the better choice.

Panels, trays, pagers

Refer to the supplemental Openbox Themes and Apps to learn about these GUI embellishments for Openbox.

File managers

Three popular lightweight file managers are:

  • Thunar. Thunar supports auto-mount features and other plugins.
# pacman -S thunar
  • ROX (ROX provides desktop icons)
# pacman -S rox
# pacman -S pcmanfm   #  PcManFM package also provides desktop icons.
# pacman -S ntfs-3g   #  Allows PCManFM to access NTFS drives.

More information is found at Openbox Themes and Apps. The supplemental article has further information about application launchers such as gmrun, clipboard managers, volume mixers, and more.

Tips and tricks

File associations

Because Openbox and the applications you use with it are not well-integrated you might run into the issues with your browser. Your browser may not know which program it is supposed to use for certain types of files.

A package in the AUR called gnome-defaults-list contains a list of file-types and programs specific to the Gnome desktop. The list is installed to Template:Filename

Open this file with your text-editor. Now you can replace a given application with the name of the program of your choosing. For example, totem <=> vlc  or  eog <=> mirage. Save the file to Template:Filename.

Another way of setting file associations is to install package perl-file-mimeinfo from the repository and invoke  mimeopen  like this:

mimeopen -d /path/to/file

You are asked which application to use when opening /path/to/file:

Please choose a default application for files of type text/plain
       1) notepad  (wine-extension-txt)
       2) Leafpad  (leafpad)
       3) OpenOffice.org Writer  (writer)
       4) gVim  (gvim)
       5) Other...

Your answer becomes the default handler for that type of file. Mimeopen is installed as Template:Filename.

Copy and paste

From a terminal Ctrl+Insert  for copy and  Shift+Insert  for paste.

Also  Ctrl+Shift+C  for copy and  mouse middle-click  for paste (in terminals).

Other applications most likely use the conventional keyboard shortcuts for copy and paste.

Window transparency

The program transset-df (virtually the same as transset) is installed with pacman -S transset-df. With transset-df you can enable window-transparency on-the-fly.

For instance by placing the following in Template:Filename you can have your mouse adjust window transparency by scrolling while hovering over the title bar (it is in the <mouse> section):

    <context name="Titlebar">
     . . .
     <mousebind button="Up" action="Click">
       <action name= "Execute" >
       <execute>transset-df -p .2 --inc  </execute>
     <mousebind button="Down" action="Click">
       <action name= "Execute" >
       <execute>transset-df -p .2 --dec </execute>
     . . .

It appears to work only when no additional actions are defined within the action group.

Xprop values for applications

If you use per-application settings frequently, you might find this bash alias handy:

alias xp='xprop | grep "WM_WINDOW_ROLE\|WM_CLASS" && echo "WM_CLASS(STRING) = \"NAME\", \"CLASS\""'

To use, run Template:Codeline and click on the running program that you'd like to define with per-app settings. The result displays only the info that Openbox requires, namely the WM_WINDOW_ROLE and WM_CLASS (name and class) values:

[thayer@dublin:~] $ xp
WM_CLASS(STRING) = "gajim.py", "Gajim.py"

Xprop for Firefox

For whatever reason, Firefox and like-minded equivalents ignore application rules (e.g. <desktop>) unless Template:Codeline is used. This applies irrespective of whatever values xprop may report for the program's WM_CLASS.

Linking the menu to a button

Some people want to link the Openbox menu (or any menu) to an object. This is useful for creating a panel button to pop up a menu. Although Openbox does not provide this, a program called xdotool simulates a keypress. Openbox can be configured to bind that keypress to the ShowMenu action.

Package  xdotool  is available in the AUR. After installing xdotool, add the following to the <keyboard> section of your Template:Filename:

 <keybind key="A-C-q">
   <action name="ShowMenu">

Restart/reconfigure Openbox. The following command summons a menu at your cursor position. The command may given as-is, linked to an object, or placed in a script.

$ xdotool key ctrl+alt+q

Of course, change the key shortcut to your liking. Here's a snippet from a tint2 (a taskbar-like panel) configuration file which pops up a menu when the clock area is clicked. Each key combination is set to open a menu within openbox's Template:Filename configuration file. The right‑click menu is different from the left‑click menu:

clock_rclick_command = xdotool key --clearmodifiers "ctrl+XF86PowerOff"
clock_lclick_command = xdotool key --clearmodifiers "alt+XF86PowerOff"

Urxvt in the background

With Openbox, running a terminal as desktop background is easy. You won't need devilspie here.

First you must enable transparency, open your Template:Filename file (if it doesn't exist yet, create it in your home folder).

URxvt*geometry:124x24    #I don't use the whole screen, if you want a full screen term don't bother with this and see below.
URxvt*foreground:Black   #Font color. My wallpaper is White, you may wish to change this to White.

Then edit your Template:Filename file:

<application name="URxvt">
  <maximized>true</maximized> #Only if you want a full size terminal.

The magic comes from the Template:Codeline line, which place the application under all others. Here Urxvt is displayed on all desktops, change it to your convenience.

Note: Instead of using <application name="URxvt">, you can use another name ("URxvt-bg" for example), and use the -name option when starting uxrvt. That way, only the urxvt terminals which you choose to name URxvt-bg would be captured and modified by the application rule in rc.xml. For example: urxvt -name URxvt-bg (case sensitive)

ToggleShowDesktop exception

Above method still minimizes Urxvt when using the ToggleShowDesktop command. A method for avoiding this is explained in this forum post. This involves editing Urxvt's source code.

Keyboard volume control

If you use ALSA for sound, you can use the amixer program to adjust the volume of sound. You can use Openbox's keybindings to act like multimedia keys. (Alternatively, you can probably find out the names of your real multimedia keys and map them.) For example, in the <keyboard> section of rc.xml:

   <keybind key="W-Up">
     <action name="Execute">
       <command>amixer set Master 5%+</command>

This binds Windows key + Up arrow to increase your master ALSA volume by 5%. Corresponding binding for volume down:

   <keybind key="W-Down">
     <action name="Execute">
       <command>amixer set Master 5%-</command>

As another example you can also use the XF86Audio keybindings:

   <keybind key="XF86AudioRaiseVolume">
     <action name="Execute">
       <command>amixer set Master 5%+ unmute</command>
   <keybind key="XF86AudioLowerVolume">
     <action name="Execute">
       <command>amixer set Master 5%- unmute</command>
   <keybind key="XF86AudioMute">
     <action name="Execute">
       <command>amixer set Master toggle</command>

The above example should work for the majority of multimedia keyboards. It should enable to raise, lower and mute the Master control of your audio device by using the respective multimedia keyboard keys. Notice also that in this example:

  • The "Mute" key should unmute the Master control if it is already in mute mode.
  • The "Raise" and "Lower" keys should unmute the Master control if it is in mute mode.

Troubleshooting Openbox 3.5

X server crashes

Problems have been detected after upgrade to ver. 3.5, that the X server might crash in attempt to start openbox, ending with similar error message:

(metacity:25137): GLib-WARNING **: In call to g_spawn_sync(), exit status of a child process \
                   was requested but SIGCHLD action was set to SIG_IGN and ECHILD was received by waitpid(), so exit \
                   status can't be returned. This is a bug in the program calling g_spawn_sync(); either don't request \
                   the exit status, or don't set the SIGCHLD action.
xinit: connection to X server lost
waiting for X server to shut down

In this particular case, some problem with metacity package has been identified as the cause of the X server crash issue. Removal of metacity & compiz-decorator-gtk packages solved the problem. Though, later was found, that even a simple reinstall of packages might have helped, as there is no problem after new installation of previously removed packages.

Also, plenty of similar cases have been found on the Internet, that not only metacity package might be causing the X server to crash. Thus, whatever else instead of metacity you get in the error output message, try to reinstall it (or remove if necessary) in an attempt to get rid of this X server crash.

Autostarting unwanted applications in 3.5

Unwanted applications do start with your Openbox session, though they are not listed in your ~/.config/openbox/autostart script?

Check the ~/.config/autostart/ directory, it might contain the residues from your previously used desktop environment (Gnome, KDE, etc.), and remove unwanted files.