Gentoo Wiki


Desktop environments

Lightweight desktop environments

Window managers

Compositing window managers


A screenshot of my fluxbox desktop.
A screenshot of my fluxbox desktop.
A screenshot of my [Amlynch] desktop.
A screenshot of my [Amlynch] desktop.


What is Fluxbox

Fluxbox is a window manager for X, based on blackbox. It is extremely fast and customizable through configuration files. Although when you first emerge it may appear too simplistic, this HOWTO will show you how to reconfigure fluxbox and add extra eyecandy/functionality.

Installation and setup

PLEASE NOTE: Gentoo has an official Fluxbox howto located at

emerge fluxbox

If you are using a login manager such as GDM, you should be able to select fluxbox from the appropriate menu. If you want to use the default XDM that comes with Xorg, edit /etc/rc.conf, and change the line XSESSION="Xsession" to XSESSION="fluxbox".

If you don't plan on using a graphical login manager then you can configure the global /etc/X11/xinit/xinitrc or the per-user ~/.xinitrc file to run it via startx.

To have fluxbox started you should include something like the following:

File: ~/.xinitrc
exec startfluxbox

Starting up other applications when you log in to fluxbox is handled by the .fluxbox/apps file which we will get to later in this document.

Basic usage

When you first start fluxbox, you should see a blank background and a little toolbar at the bottom. The interface is fairly intuitive. Right-clicking on the background pops out the fluxbox menu. The toolbar works as expected, showing the icons of every open window. The screen is divided into four workspaces by default, in a similar way to KDE. This means that applications that are open in one workspace won't show up on the other ones. You can also move applications through workspaces by selecting Send To... in their right-click menus, or by dragging the window to the edge of the screen.

Now that you have a working Fluxbox installation, you will first want to customize the functionality to your needs and work habits. Let's check the files in the ~/.fluxbox directory.

Enabling unicode support

If you have your system configured to use unicode, you might want Fluxbox to use unicode too. Fluxbox comes with some styles most of which are selecting fonts that are not fully suitable for unicode. To fix this you will have to edit the Fluxbox's stylefile(s) in /usr/share/fluxbox/styles and add something like:

File: /usr/share/fluxbox/styles/$YourStyle
window.font:                         -*-*-*-*-*-*-*-*-*-*-*-*-*-u

to at least fix the window title bug.

Solution by user Holms:

Another solution is to set locale in ~/.xinitrc For example I'm using Cyrillic most of a time. If you will write this in your ~/.xinitrc

File: ~/.xinitrc
 export LANG="ru_RU.UTF-8"
 export LC_ALL="ru_RU.UTF-8"

then all windows title will be in unicode and your locale will be Russian, set this to your country. Maybe it will be clever to put en_EN.UTF-8 instead of that, because all programs will start display everything in your language instead of english. UTF-8 shows to the system which encoding you'll be using by default so you want Unicode you'll get Unicode. By the way add same two line to the ~/.bashrc (at least some people prefer to do this, but didn't helped to me) and do not forget to configure your locales in /etc/locale.gen. If you haven't configured it yet, go to Gentoo handbook and read about locales. If this doesn't help try to read HOWTO_Xorg_and_Fonts. Do everything that written in "Emerging the necessary packages" section, at least that helped to me.

Generating ~/.fluxbox/menu


To keep your menu up to date after merging or unmerging applications, use the menu generator that comes with fluxbox, simply run it like so:

fluxbox-generate_menu -ds -is

It will search for the applications installed and create a new ~/.fluxbox/menu file. As some applications are still missing in this script you may add them editing /usr/bin/fluxbox-generate_menu (as root).

Also it will install a ~/.fluxbox/menuconfig which you can customize to your liking, for example, to add gnome or kde support or to change the default browser or term.

To enable easy customizing of the menu, fluxbox-generate_menu looks in ~/.fluxbox/usermenu for settings that will appear in a user submenu.

The location can be changed by running fluxbox-generate_menu with the "-u <path>" option.


Menu Maker is a program meant to integrate the menus of different window managers, in such a way to keep it consistant between them

Since it isn't part of fluxbox, you must emerge it to run it ( emerge -va menumaker ), then run

mmaker -v fluxbox

Note that it adds a lot to your menu

This is just a script to allow you to emerge things straight from your portage menu, it is incredibly laggy on my system, but in case you want it:


# from
# modified by to add -a option and sudo


source /etc/make.conf
source /sbin/

if [ -e ${OUTFILE}.lock ]; then
        ewarn "Refusing to load another session for $$"
        exit 0
touch ${OUTFILE}.lock
echo $$ > ${OUTFILE}.lock

[ -e "$PORTDIR" ] || PORTDIR=/usr/portage


echo \[begin\] \(Portage @TOTAL@\) > $OUTFILE
echo \[submenu\] \(Portage @TOTAL@\) >> $OUTFILE
find ${PORTDIR} -name '*[a-z]-[a-z]*' -type d -maxdepth 1 | while read line; do
        # [ -f /usr/bin/beep ] && beep -n 1 -r 1
        pushd $line > /dev/null
        count=$(find . -type d -maxdepth 1 | cut -c 3- | grep -v ^CVS$ | grep -v ^$ |wc -l | awk '{print $1}')
        category=$(basename $line)
        # [ -w /dev/speech ] && echo $category > /dev/speech &
        echo -ne '\t' >> $OUTFILE
        echo \[submenu\] \(${category}\) \{$count packages\} >> $OUTFILE

        find . -type d -maxdepth 1 | cut -c 3- | grep -v ^CVS$ | grep -v ^$ | while read dname ; do
                echo -ne '\t\t' >> $OUTFILE
                #/usr/lib/portage/bin/portageq has_version / $category/$dname
                #if [ "$ret" == 0 ] ; then
                #       vname=$(basename $(/usr/lib/portage/bin/portageq best_version / $category/$dname))
                echo \[exec\] \($vname\) \{ xterm -rv -e \"sudo emerge -va $category/$dname \; bash --login\" \} >> $OUTFILE
                let ++TOTAL
        echo -ne '\t' >> $OUTFILE
        echo \[end\] >> $OUTFILE
        popd $line > /dev/null

echo \[end\] >> $OUTFILE
echo \[end\] >> $OUTFILE
sed -e "s:@TOTAL@:${TOTAL}:g" < $OUTFILE > $OUTFILE~ && cp $OUTFILE~ $OUTFILE

[ -f /usr/bin/beep ] && beep -n 1 -r 5

rm ${OUTFILE}.lock

You can use this by adding "[include] (~/.fluxbox/portage_menu)" to ~/.fluxbox/menu if you make your own, or add it to ~/.fluxbox/usermenu if you use fluxbox-generate_menu

I found this script useful although I couldn't fit all the menu on one screen this helps... improvements still needed though.

< #!/bin/sh
> #!/bin/bash
> #modified so it would fit on one screen
> 	#counter
> 	i=0;
> 	if (( $lock )); then
> 	echo unlocked
>         echo -ne '\t' >> $OUTFILE
> 	echo \[end\]  >> $OUTFILE
> 	lock=0
> 	fi
<         find . -type d -maxdepth 1 | cut -c 3- | grep -v ^CVS$ | grep -v ^$ | while read dname ; do
>         while read dname ; do
<                 echo \[exec\] \($vname\) \{ xterm -rv -e \"sudo emerge -va $category/$dname \; bash --login\" \} >> $OUTFILE
> 		let ++i;
> 		if (( i!=0 && i % 100 && i % 50 == 0 )); then
>         	echo -ne '\t' >> $OUTFILE 
> 		echo \[submenu\] \(more\) {} >> $OUTFILE
> 		echo locking
> 		lock=1
> 		fi
> 		if (( i!=0 && i % 100 == 0 )); then
>         	echo -ne '\t' >> $OUTFILE
> 		echo \[end\]  >> $OUTFILE
> 		echo unlocking
> 		lock=0
> 		fi
>                 echo \[exec\] \($vname\) \{ xterm -rv -e \"emerge -va $category/$dname \; bash --login\" \} >> $OUTFILE
<         done
>         done < <(find . -type d -maxdepth 1 | cut -c 3- | grep -v ^CVS$ | grep -v ^$)

patch <


Heres another scipt to generate things to get included by fluxbox's menu, this must be run as root, forgot where i got this from, but here:

File: fbprocmenu
#!/usr/bin/env python

#------------------------ process info script for fluxbox menu ------------------

import sys, os
from os.path import isdir, isfile, join
from time import sleep
def getprocesses():
    """Sort out process ids from /proc"""
    proccontent = os.listdir("/proc")
    dirsonly = [d for d in proccontent if isdir(join("/proc", d))]
    proclist = [elem for elem in dirsonly if elem[0] in ['1', '2', '3', '4', '5', '6', '7', '8', '9']]
    return proclist

def getprocinfo(procid):
    """Get info about an individual process."""
    procinfo = {}
    procpath = "/proc/%s/status" % procid
    statfile = open(procpath, 'r')
    procinfo["pid"] = procid
    for line in statfile.readlines():
        if "Name" in line:
            procinfo["Name"] = line.split(":")[1].strip()
        elif "State" in line:
            procinfo["State"] = line.split(":")[1].split(" ")[0].strip()
    return procinfo

def makeprocdictlist(proclist):
    """Construct list of procinfo dictionaries"""
    #procdictlist = [getprocinfo(pid) for pid in proclist]
    procdictlist = map(getprocinfo, proclist) 
    return procdictlist

while 1:
    procs = getprocesses()
    info = makeprocdictlist(procs)
        outfile = open('/usr/share/commonbox/fbprocmenu.txt', 'w+')
        outfile.write('[begin]  (procinfo) {}\n')
        for elem in info:
            line = "[submenu]  ("+elem["Name"]+" "+elem["pid"]+" "+elem["State"]+") {}\n    [exec] (kill) {kill -9 "+elem["pid"]+"}\n   [exec]"\
                +" (restart) {kill -18 "+elem["pid"]+"}\n    [exec] (terminate) {kill -15 "+elem["pid"]+"}\n[end]\n"
    except IOError:
        print "Cannot create fbprocmenu file."

You can use this by adding "[include] (/usr/share/commonbox/fbprocmenu.txt)" to ~/.fluxbox/menu if you make your own, or add it to ~/.fluxbox/usermenu if you use fluxbox-generate_menu

Here's another script I cooked up to convert what gnome thinks the menu should be into fluxbox syntax. It uses the output of gnome-menu-spec-test and some find/slocate commands to best guess the icons then prints the results to stdout. One can then redirect the output to a file of their choice and include it inside the main menu file. I've found it to work pretty well.

#!/usr/bin/perl -w 
# 2008-06-17
# This script uses the output of gnome-menu-spec-test to make a similar menu
# for fluxbox.  
# The format of that ouput is: "category/ app.desktop /path/to/app.desktop"
# Each *.desktop file includes many entries including, but not limited to,
# Categories, Name, Exec, Icon
# We'll loop through each item, read its .desktop, and create a hash of the
# appopriate data: submenu, name, exec, pixmap.
# The trouble for is resolving the Icon to an actual filename.  In most cases
# there are many files that could satisfy it or it is difficult to find the
# location of the icon at all.  In theory there's an xdg or gtk mechanism to
# discover the appropriate icon, but since I don't know it at the moment I'll
# either equery or slocate it.

use strict;

# declare some subs - see below for descriptions.
sub findIconPath($$$);

# A hash to store our new menu data in.
my %data;

# start looping through what gnome thinks the menu should look like
# NOTE: this does not include items from the System menu.
my @output = `gnome-menu-spec-test`;
foreach my $item (@output) {
	$item =~ /^(.+)\/\s+.+\.desktop\s+(\/.+\.desktop)$/;
	my $submenu = $1;
	my $file = $2;

	# open the .desktop file and put it in an array
	my $rc = open(FILE, '<', $file);
	if (!$rc) {
		print STDERR "Couldn't read from $file.\n";
	my @file = <FILE>;
	# loop through the .desktop file's content and find the import fields
	my ($name, $exec, $icon);
	foreach my $line (@file) {
		if ($line =~ /^Name\s*=\s*(.*)/) {
			$name = $1;
		elsif ($line =~ /^Exec\s*=\s*(.*)/) {
			$exec = $1;
		elsif ($line =~ /^Icon\s*=\s*(.*)/) {
			$icon = $1;
	$data{$submenu}{$name}{'exec'} = $exec;
	$data{$submenu}{$name}{'icon'} = findIconPath($name, $exec, $icon);

# Now that we have a hash representing our new menu, loop through it and print
# it in fluxbox syntax.
foreach my $submenu (sort(keys(%data))) {
	print "\t[submenu] ($submenu)\n";
	foreach my $name (sort(keys(%{$data{$submenu}}))) {
		my $temp = $name;
		$temp =~ s/(?!\\)(\))/\\$1/g;
		my $exec = $data{$submenu}{$name}{'exec'};
		my $icon = $data{$submenu}{$name}{'icon'};
		print "\t\t[exec] ($temp) {$exec} <$icon>\n";
	print "\t[end]\n";

exit 0;

################################## END MAIN ###################################

# findIconPath($name, $exec, $icon)
# attempts to find an icon for the given application using equery and/or slocate.
# eventually this should use some xdg or gnome mechanism
# @param $name The name of the application.
# @param $exec The executable name.
# @param $icon The icon name (probably the same as name).
sub findIconPath($$$) {
	my ($name, $exec, $icon) = @_;
	# if the icon given is an actual path, just return it
	if ($icon =~ /^\// && -f $icon) {
		return $icon;

	# TODO: lots of smart things to find an icon

	# check the default icon paths
	my $temp = "find /usr/{local,}/{kde/*/,}share/icons/{gnome,gentoo,hicolor} /usr/share/pixmaps -name '*$icon*' 2>/dev/null | egrep '\.(png|xpm|ico)\$' | tail -n1";
	#print $temp, "\n";
	$temp = `$temp`;
	if ($temp) {
		return trim($temp);

	# TODO: do an equery search

	# use an slocate search
	$temp = "locate '$icon' 2>/dev/null | egrep '^/usr/(local/)?(kde/.*/)?share/(icons|pixmaps).*\.(xpm|png|ico)\$' | tail -n1";
	#print $temp, "\n";
	$temp = `$temp`;
	if ($temp) {
		return trim($temp);

	return "";

sub trim {
	my ($str) = @_;
	$str =~ s/^\s*//;
	$str =~ s/\s*$//;
	return $str;


See Denu at Sourceforge. Denu is an automatic menu generator for many windowmanagers, including Fluxbox, complete with icons.

Startup Applications

The first step in customizing Fluxbox is to set programs that will be run when you start it up. There are three ways of doing this:

This preferred approach only works when you are using startfluxbox to fire up fluxbox, which should be the default way in Gentoo's session-scripts for kdm/gdm/xdm. an example ~/.fluxbox/startup will be created with the first use of startfluxbox.

Edit ~/.fluxbox/startup, and add the names of each application that you want to start with fluxbox on their own lines and be sure to put an ampersand at the end (&). Then the only thing you will need to include in the ~/.xinitrc or ~/.xsession (depending on where fluxbox is started from) is "startfluxbox" (if you are modifying an existing fluxbox installation, replace the "fluxbox" statement by "startfluxbox", do not just add the line).

Some prefer this approach, since it works even if you are not using "startfluxbox" or some session-script which does not use "startfluxbox" (eg GDM in some cases). By default, gdm just checks the scripts in /etc/X11/Sessions and not .xinitrc and .xsession. Add fluxbox and any other application you want autostarted here.

This option is fairly pointless unless you need something that the other two methods do not provide. First, open the ~/.fluxbox/init file with your favorite editor and have a look at the hints and examples in it:

Now find the line that says rootCommand, and change it to:

write full name.rootCommand: ~/.fluxbox/

Go to the .fluxbox folder, create the file and make it executable

cd ~/.fluxbox/
nano -w ./
chmod +x ./

In this file, you can add as many programs as you want, such as gaim and aterm. Just be sure to put the ampersand (&) sign at the end of every line so that the execution is not delayed (this can be the expected behavior sometimes).

The basic difference between first/second and third approach is, that the third approach is executed after fluxbox starts living and the other two are executed before fluxbox starts. That makes it pretty hard (aka impossible) for the third approach to set some environment-variables.

The Desktop

Setting the wallpaper using fbsetbg

Fbsetbg comes standard with fluxbox and is a clever wrapper script to set the background using any installed application which supports such features (xsri, feh, eterm, xv). Not all these applications support pseudo transparancy (needed for transparancy in xchat for example). feh is a popular choice as it is small, fast and supports transparancy. So to start, lets install feh:

emerge -av feh

Then to make sure that fsetbg knows that feh is what you plan on using, run:

fbsetbg -i

It should say something like "feh is a nice wallpapersetter. You won't have any problems." If this is the case, then you can go on to set the background. If it says you are using some other application, then you can either choose to continue or put wpsetters=feh infront of fbsetbg.

This command will set a jpeg image as a fullscreen background:

fbsetbg -f /path/to/image.jpeg

This command will set a jpeg image as a fullscreen background using feh even if fbsetbg -i said something different:

wpsetters=feh fbsetbg -f /path/to/image.jpeg

You can make this happen every time you start fluxbox by adding the command to the ~/.fluxbox/init file. Find the line beginning with session.screen0.rootCommand: and enter the proper command afterward. You can also use the simplified command fbsetbg -l to load the last wallpaper loaded by fbsetbg, to avoid changing the init file each time you change your wallpaper.

For more information on fbsetbg check the man page.

More feh goodies

Another neat thing you can do with feh is to use it with Fluxbox's wallpaper menu option. This option gives you a wallpaper list off your Fluxbox menu, and is implemented as such:

[submenu] (Wallpaper)
     [wallpapers] (/path/to/wallpaper) {feh --bg-scale}

Use whatever commandline option you wish with feh; I use --bg-scale. You can run this in your ~/.fluxbox/startup script, to use feh to set the wallpaper to the last one it was:

fbsetbg -l

This will prevent you from having to set the wallpaper again everytime you start Fluxbox. Note: the default startup file has a line setting a solid black background: "/usr/bin/fbsetroot -solid black"; ensure you comment the line.

Alternative Random Wallpaper

Fbsetbg has a nice little feature that allows one to randomly choose wallpaper. Alternatively, you can also use Esetroot in place of fbsetbg -r /dir/name. To do so use this little script:

Background=$(ls ${LOCATION})
background=($Background)                # Read into array variable.
num_background=${#background[*]}        # Count how many elements.
Esetroot ${LOCATION}/${background[$((RANDOM%num_background))]}

This example uses Esetroot which is a componant of Eterm, but you may insert your own wallpapger/background chooser.

Setting wallpaper using overlay file

In addition to the style file, the overlay file, whose location is specified by session.screen0.styleOverlay (default: ~/.fluxbox/overlay) can be used to set style resources that override all styles. For more information about which parts of fluxbox can be controlled by the overlay file, see fluxstyle(1).

Every style must specify the background option. If you don't want your style to change the user's background, then use `background: none'. The options `centered', `aspect', `tiled', and `fullscreen' require the `background.pixmap' resource to contain a valid file name. The `random' option requires `background.pixmap' to contain a valid directory name. For these options, fluxbox(1) will call fbsetbg(1) to set the background. The options `gradient', `solid', and `mod' all require `background.color' to be set. `gradient' and `mod' both require `background.colorTo'. `mod' requires `background.modX' and `background.modY' to be set as well. These options will be passed to fbsetroot(1) to set the background.

  background: centered|aspect|tiled|fullscreen|random|solid|gradient <texture>|mod|none
  background.pixmap: <file or directory>
  background.color: <color>
  background.colorTo: <color>
  background.modX: <integer>
  background.modY: <integer>

In a simple way, you can write in your overlay file something like this:

  background: random
  background.pixmap: /path/to/backgrounds-directory

So fluxbox will chose a random wallpaper from /path/to/backgrounds-directory for you on startup.

Icons using Idesk

Idesk is a nice program for creating clickable, themeable icons on the desktop. You can use PNG or SVG images as icons and several premade icon packs are available.

To start, we should install idesk:

emerge -av idesk

Now create a file in your home directory called ~/.ideskrc and add the following content:

File: ~/.ideskrc
table Config
FontName: verdana
FontSize: 12
FontColor: #ffffff
Locked: false
Transparency: 100
Shadow: true
ShadowColor: #000000
ShadowX: 1
ShadowY: 2
Bold: false
ClickDelay: 300
IconSnap: true
SnapWidth: 55
SnapHeight: 100
SnapOrigin: BottomLeft
SnapShadow: true
SnapShadowTrans: 200
CaptionOnHover: false
table Actions
Lock: control right doubleClk
Reload: middle doubleClk
Drag: left hold
EndDrag: left singleClk
Execute[0]: left doubleClk
Execute[1]: right doubleClk

Now create a directory called ~/.idesktop/ also in your home directory. This is where you will be storing the icons you want to use along with info on what the icons do. Make one file for each icon you want, for example, for the HOME icon, we would create a home.lnk:

File: home.lnk
table Icon
Caption: Home
Command: rox
Icon: /home/ikaro/.idesktop/home.png # the image to be used as an desktop icon

Do the same for the other icons you want.

Start idesk like this:

nohup idesk > /dev/null &

Make sure that you only run idesk once, and dont have multiple instances running at the same time. After you have your icons finished and where you want them in the desktop, change Locked from 'false' to 'true' in .ideskrc. Add 'idesk' to your ~/.fluxbox/startup or other startup script to run it automatically when you start X.

Icons using ROX-Filer

First you must enter

emerge rox
emerge rox-session

In ~/.fluxbox/startup or ~/.fluxbox/ add one line

rox --pinboard=Default &

That's all! Now you can see icons on desktop and choose any wallpaper what you want!

Installing extra styles

Most *box styles will work with fluxbox and a very large selection of them can be installed as follows:

emerge -av commonbox-styles commonbox-styles-extra fluxbox-styles-fluxmod

Those three packages contain a great many styles which should be enough to satisfy most peoples needs. The fluxbox-styles-fluxmod ebuild is updated fairly regularly too so keep an eye on that one.

Icons in Menu

If you want include some icons in your menu use this...

      [exec] (gnome-terminal) {gnome-terminal} <~/.icons/xterm.xpm>
      [exec] (firefox) {firefox} <~/.icons/firefox.xpm>
      [exec] (Run) {fbrun } <~/.icons/run.xpm>

Note 1:

only working with version 0.9.10 and above

Note 2:

you can only use xpm images.
version 0.9.12-r1 supports png and jpg over imlib2 support

Using GTK+ themes

If you want to use gtk+ themes into fluxbox (and you don't have any other installed WM to use) you may consider following the tip Change Appearance of GTK Applications.

Note: If you have Xfce installed you can edit your ~/.fluxbox/startup file and add the command xfce-mcs-manager &. Just restart fluxbox and use Xfce control panel (xfce-setting-show) to choose your theme.

USE flags

Existing USE Flags for fluxbox are:

gnome imlib kde nls truetype xinerama

Adds gnome support to fluxbox. For example, if you use gaim you will see a gaim icon in systray. Also required for the ExecCommand feature of the keys file

Support for PNG, JPG, etc. pixmaps

Adds kde support to fluxbox. For instance, if using kopete you will see a kopete icon in systray.

Adds national language support in fluxbox. You may see messages in your own language.

Better fonts

Adds support for multiple screens, for those who have two or more monitors.

Tries to make theme fonts slightly less unreadable

Installing gkrellm

gkrellm is a program that can show you some handy information about your computer such as CPU usage, NIC usage etc.

First we emerge gkrellm:

emerge gkrellm

This will install gkrellm and gkrellmd for you. To fire it up:

 nohup gkrellm > /dev/null &

Then, right-click on the top of it and press Configuration for settings.

or we put gkrellm in .fluxbox/

File: ~/.fluxbox/
gkrellm &

Then save it and close it. Now it will start every time you restart fluxbox.

Note!!: If you would like to have gkrellm start in a slit.

In ~/.fluxbox/

File: ~/.fluxbox/
gkrellm -w &


Retrieved from ""

Last modified: Sat, 06 Sep 2008 07:37:00 +0000 Hits: 162,311