From Gentoo Wiki
Jump to: navigation, search
This page contains changes which are not marked for translation.

Other languages:
English • ‎日本語 • ‎한국어

This howto will show you how to set up the Fluxbox window manager for X11.


Introduction to the Fluxbox window manager

For those who are unfamiliar with Linux's desktop model, window managers (WMs) are the applications which are run by X11 to manage other graphical programs. WMs control where each window is placed, its size, and which desktop(s) have access to it. This can be done automatically via a set of user-defined rules or can be done at runtime with the mouse and possibly keyboard shortcuts, depending on the specific WM.

Some WMs, however, take on more functionality than just window management. Fluxbox also provides a platform for launching applications, configuring keyboard shortcuts and background images, as well as displaying information with the slit. GNOME's default WM, Metacity, does not include these things, but they are available through other GNOME programs. Thus, one cannot truly say that Fluxbox is a lightweight WM. However, since Fluxbox includes everything necessary for a basic desktop, many people use it in place of larger desktop suites like GNOME or KDE.

To make things even more confusing, however, Fluxbox can replace the default WM for GNOME or KDE. For example, some people find that Metacity, GNOME's window manager, simply does not have the flexibility they need, but that Fluxbox does not have all the built-in applications and integration they desire from a complete desktop environment. Thus, a person could use Fluxbox to manage the windows and GNOME for the rest. Note, however, that with this setup there are some issues caused by overlapping feature sets.

Fluxbox can also be expanded by third party software. This is often ideal in situations where hardware resources are limited, or even just as a matter of personal taste.

This guide is aimed at those who are new to Fluxbox, curious, or who are just wanting to get more out of the Gentoo/Fluxbox experience. This guide will also illustrate how to get more (yet quite optional) functionality by using third party programs which work well with Fluxbox.

Installing Fluxbox

Base installation

First, make sure you've installed a working X environment, as shown in the X Server Configuration HOWTO.

Before you install Fluxbox, you should take a look at some of the available USE flags.

While the gnome and kde USE flags are provided to give compatibility with these environments, it has been the author's experience that these USE flags are not needed. If you desire qt, gtk+, or any KDE/GNOME utility then you are free to emerge and configure those independently. The gnome and kde flags simply add support for the respective protocols, and do not depend on external libraries. However, they do increase the Fluxbox binary size.

There is also a vim-syntax flag to make configuration easier later on. This flag will install fluxbox-syntax, a special Fluxbox color scheme for vim. This enables users to more readily see the contents of their keys and init files for Fluxbox. It's a tiny extension for vim, so it's highly recommended.

Finally, there are two flags that customize the functionality of Fluxbox, slit and toolbar. These flags are provided so that users who don't need the slit or the toolbar can compile Fluxbox without them. This is useful if you want to run an extremely minimal environment, or if you plan to use different applications that provide these features, such as standalone panels or docks.

Once you've decided on your USE flags, add them to /etc/portage/package.use:

root #echo "x11-wm/fluxbox -gnome -kde truetype vim-syntax" >> /etc/portage/package.use

It is also necessary to have a program lock the X display to prevent unauthorized access, so it would be wise to also emerge xlockmore. The vast majority of users will also want the ability to set their own background, so we will emerge eterm, which doubles as a nice X11 terminal.

root #emerge --ask fluxbox xlockmore eterm

Well, that's it; Fluxbox is now installed! However, it is likely that you will not be able to use it efficiently with just those tools. The following sections will help install other potentially necessary packages, and configure Fluxbox and the third party programs to work for you. Keep in mind that all these steps are optional, so feel free to pick and choose.

Configuring Fluxbox

Preparing X11

Fluxbox is simply another program that X11 runs. If desired, one can startx and then type fluxbox at an xterm. However, this is annoying to say the least. If one does not desire to boot to the GUI, but instead wants to start X11 manually, it is possible to have X automatically load Fluxbox by executing, as a normal (non-root) user:

user $echo "exec startfluxbox" > ~/.xinitrc

This is also not ideal for most users, as they want to have the desktop environment all the time; it is a pain to startx if it is desired to use a GUI everytime you boot. It also presents a security risk to the unaware. If one locks the X11 display using xlock, but run X11 from a console, then someone with physical access to the computer can switch to that console, kill X11, and use your account. The only way to prevent this is to either background X11 or run it in screen, detach the screen, and then logout of the console, a tedious task at best. If one uses a graphical login manager, this problem does not exist. However, you will be running X11 as root, which may be a bad thing. There are, as of this writing, no exploits that the author is aware of for the current version, but if one is concerned, then either not use X11 or use the above method with screen. Note that this is not a Fluxbox issue, but affects X11 itself.

There are a number of graphical login managers to choose from; we will be using SLiM. You may use another manager at your option, but SLiM works well for Fluxbox, as well as any other environments you may have installed such as GNOME, KDE, or Xfce.

root #emerge --ask slim
root #rc-update add xdm default
Be sure to emerge slim and add xdm to the bootscript, and not the other way around! Switching these will cause failure. We will also need to modify one system-wide config file:
FILE /etc/conf.d/xdm Setting the display manager to slim

Themes and Artwork

This section can be skipped if one truly wants a minimal footprint. However, it is nice to allow users to customize their WM's appearance. Themes specific to Fluxbox, Gentoo artwork for any WM, and themes that can be used on any *box WM will be installed.

root #emerge --ask commonbox-styles commonbox-styles-extra fluxbox-styles-fluxmod gentoo-artwork

Running Fluxbox for the first time

Now you are ready to run Fluxbox for the first time. It will create a directory called ~/.fluxbox/ in your home directory, which is where Fluxbox stores all its settings, and populate it with some default values.

user $startx

If you've installed SLiM or another display manager, start it by becoming root and running:

root #/etc/init.d/xdm start

Then choose Fluxbox as your session and login with your regular user.

Once Fluxbox is running, it will look pretty plain. You should see a blank desktop with a toolbar at the bottom. You can then right-click anywhere on your desktop to bring up the menu. From there you should be able to start up any X applications you would like to run, or open up a terminal from which you can run anything you like.

Fluxbox Keys

Fluxbox comes with a very weak set of default keysets. It enables a user to switch windows and desktops, and no more. Before changing it, there are a few things necessary to know. In the Fluxbox keys file, there are some strange modifiers. Mod1 is commonly known as the "Alt" key, and Mod4 is the unspeakable (windows) key. Control and Shift are Control and Shift. However, it is usually best to use Alt/Windows keys because other X11 programs tend to use Control and Shift for their own shortcuts.

All of these are independent, so feel free to leave out anything not desired, or modify this to your own needs. This guide uses what the author assumes to be the most common programs, so also substitute the name of the package used if it differs from what appears here. For more information, read the man page for Fluxbox.

So, with that out of the way, fire up a text editor (non-root user), point it to ~/.fluxbox/keys, and lets upgrade those shortcuts!

FILE ~/.fluxbox/keys Modifying keyboard shortcuts
# locks X11 display to the current user
Mod4 l   :ExecCommand xlock
# opens a number of programs with quickkeys. These are just examples, I am sure
# you get the point...
Mod1 f   :ExecCommand firefox
Mod1 t   :ExecCommand thunderbird
Mod1 o   :ExecCommand oowriter
Mod1 v   :ExecCommand gvim
# Fluxbox has no sound control, so we need to do a hack to get one
# (assumes alsa usage. if you use oss, then you are on your own)
Mod1 e   :ExecCommand Eterm -name alsa -e alsamixer
# This launches fbrun, which in turn launches other programs
Mod1 r   :ExecCommand fbrun
# Program Control. It just makes life simpler...
Mod1 4   :Close
Mod1 m   :Minimize
# if you have aterm (emerge x11-terms/aterm), then this opens a really nice
# transparent aterm with no borders, fitting nicely with 1024x768
# resolution, while still leaving room for conky. Once again, feel free to
# modify.
Mod1 a   :ExecCommand aterm -name aterm -sl 3000 -tr +sb -sr -sk -bg black -fg \
white -fade 90 -bl -tn xterm -fn \
-misc-fixed-medium-r-normal-*-*-120-*-*-c-*-iso8859-15 -g 116x57
# similar to the above, but opens a transparent rooted terminal. you must, of
# course, know the root password to use this
Mod1 s   :ExecCommand aterm -name aterm -sl 3000 -tr +sb -sr -sk -bg black -fg \
white -fade 90 -bl -tn xterm -fn \
-misc-fixed-medium-r-normal-*-*-120-*-*-c-*-iso8859-15 -g 116x57 -e su -

System Monitor

It is a common desire to setup a system monitor for X11 on desktop systems. Gkrellm is a commonly used monitor, but in the spirit of Fluxbox minimalism, we are going to use a simpler monitor: conky. If desired, use another monitor; there are plenty of HOWTOs elsewhere.

root #emerge --ask conky

The default config file for Conky is rather weak, but more info can be found by reading the manpage or the Gentoo Linux Conky Howto.


Fluxbox does not come with a utility or program to draw icons to the desktop; everything is handled by keyboard shortcuts, or the right-click menu. iDesk is a program that can be used to fulfill this need. It is aimed at users of minimal WMs like ourselves who want to display icons in the root window, and it even supports funky graphic effects like transparency! Despite its name, iDesk is not affiliated with Apple or Mac (to the best of the author's knowledge). Installing iDesk is as simple as:

root #emerge --ask idesk

Once installed, it will be necessary to configure iDesk so that it is able to display the icons we desire. Its configuration file can be found at ~/.ideskrc. This is a rather lengthy task, and can't be well covered in this guide. The following resources might be useful in order to help you configure iDesk: man idesk, iDesk's Usage Guide and this thread in the Gentoo Forums.

Graphical File Manager Options

It is important to note that Gentoo does not need a file manager. It is perfectly possible, and indeed simpler (in the author's humble opinion), to do all the file manipulation by command-line. However, not everyone agrees...

Many users who are new to Gentoo/Fluxbox are put off by the lack of a graphical file manager such as nautilus in GNOME. Fluxbox itself does not provide such a program, but as always, it is simple to acquire one. There are many choices, but this guide will present three, one for the gentoo who likes text only and two for the user who likes rox to thunar. It is also possible, of course, to install all three and try them out.

Gentoo File Manager - Minimalism

Gentoo is a file manager which seeks to provide the benefits of a GUI interface without all the bloat which is commonly associated with such interfaces.

root #emerge --ask gentoo
The Gentoo file manager is a separate project from the Gentoo Linux distribution. For more information on this, see the Gentoo Name and Logo Usage Guidelines.

The Gentoo file manager aims to be fully configurably via GUI, so feel free to tweak.

Rox File Manager - Includes Icons

Rox is a file manager which uses icons as well as text and is much more like Windows' Explorer.

root #emerge --ask rox

Rox behaves much like "traditional" file managers, so its interface should be intuitive. If not, there always are manpages.

Thunar File Manager

Thunar is a lightweight, fast file manager that, like Rox, behaves much like "traditional" file managers. It includes icons and text, and it's easy to use. Though originally designed for Xfce, it's a nice complement to a Fluxbox-based system.

root #emerge --ask thunar

Picture Viewer

Many WMs come with utilities to view pictures in a directory. These applications are small and lightweight, and do not allow for editing (which is assumed to be done by the gimp or similar). This is necessary if you use a command line, gentoo, or rox for a file manager. Though thunar can display image thumbnails, a separate lightweight image viewer is still a good idea.

root #emerge --ask gqview

gqview can be launched in any directory, and can browse through any supported picture format.

Setting a theme, background, and a startup script

Fluxbox has a number of themes that can be accessed by the right click menu, then "Fluxbox menu," and "System Styles." These themes usually set their own background, which is either a single color or a gradient of some type. Most people prefer to set their own background, and keep it no matter what theme they chose. To do so, we need to edit another of Fluxbox's files, which governs startup behavior. So fire up that text editor again, and point it to ~/.fluxbox/startup.

If this file exists, then clear it. Add the following to the newly created file, uncommenting as needed, and filling in values for the CAPS.

FILE ~/.fluxbox/startup Editing startup scripts for Fluxbox
# Gentoo's Fluxbox startup script
# Programs which need to run constantly, as opposed to a one time execution,
# need "&" at the end of the command.
# Show the Fluxbox splash-screen
#fbsetbg -C /usr/share/fluxbox/splash.jpg
# This sets a background. You must have a program setup to do this
# (x11-terms/eterm is recommended)
#fbsetbg -f PATH_TO_IMAGE
# Custom fonts directory
# Starts the icons program
#idesk &
# This MUST be the last command!
exec /usr/bin/fluxbox -log ~/.fluxbox/log

Menu generation

The author uses a text editor to create menus. If this sounds appealing to you, please skip this section and proceed to Editing Menus by Hand.

It is possible to edit ~/.fluxbox/menu by hand after using an automatic generator (see next section), to either add packages or delete those which aren't used. Note that if something is deleted from this menu, it does not delete the package from the system, just from the individual user's menu. The program can still be run by command-line.

There is a program already on your system called fluxbox-generate_menu, which can be used to generate menus. To run it (as a non-root user):

user $fluxbox-generate_menu -is -ds

It is recommended that you use the fluxbox-generate_menu listed above instead of other programs, which do not understand Gentoo's directory structure.

This can also be done from the Fluxbox menu itself. There is usually an entry in the "Fluxbox" menu called "Regen Menu" which will re-run this script, looking for any new applications that have been installed since the last time you ran it.

It is possible to use this method to auto-generate menus and still have some manual control over your menu. Creating and editing ~/.fluxbox/usermenu by hand (see the next section for syntax) will give a user a personalized menu which will not be erased the next time the script is run.

Editing Menus by Hand

Fluxbox's menu is a text file that follows a quite simple syntax, described in this section. The default menu definition is present in the ~/.fluxbox/menu file.

Menu entries for executing applications are defined by the [exec] element. You can define an entry, either under the [begin] definition (the menu root), or between a [submenu] and its corresponding [end] line (submenu definitions), for example:

FILE ~/.fluxbox/menu Defining new menu entries
# Custom fluxbox menu
[begin] (Fluxbox)
  [exec] (XTerm White on Black) {xterm -ls -fg white -bg black}
  [submenu] (More terminals)
    [exec] (Aterm default) {aterm}
    [exec] (Rxvt default) {rxvt}

The root menu definition begins with the [begin] tag, followed by its name, between parentheses and ends with its corresponding [end] tag. All the menu commands (called here, tags) are enclosed by square brackets, menu names will be enclosed between parentheses and the actual commands are enclosed between braces. Comments are allowed in this file, for lines beginning with #.

In the example shown above, the first [exec] line defines a new entry named "XTerm White on Black", which will execute xterm -ls -fg white -bg black as if from a command line. Next is a submenu which is defined using the [submenu] tag, and after that a section called "More terminals", with two more [exec] commands. Any submenu definition must have its corresponding [end] tag.

There are other menu commands that you can use in your ~/.fluxbox/menu file. Please read the official documentation available online for more information.


  • The Fluxbox wiki
  • Fluxbox developers and users in #fluxbox on chat.freenode.net


Congratulations! Fluxbox is now installed, configured, and ready to go. If any questions or suggestions come to mind, please email the author and/or file a bug report at Gentoo's Bugzilla.
This article is based on a document formerly found on our main website gentoo.org.
The following people have contributed to the original document: Jonathan Smith, Alin Dobre, Joshua Saddler, lack
They are listed here as the Wiki history does not provide for any attribution. If you edit the Wiki article, please do not add yourself here, your contributions are recorded on the history page.