Blackbox (and bbkeys) for the Impatient

Note: I haven't used blackbox for a couple of years now. This page is rather outdated. For instance, the bbkeys syntax has changed considerably but their manpage gives excellent examples.(I'm leaving my information there for those who use older versions.)

As Linux and FreeBSD become more popular, perhaps due to public resentment of MS's newest registration demands for XP (which even some long time Microsoft fans are calling the "regworm") one of the things that appeals, even to the neophyte, is the wide choice of window managers. This article covers getting Blackbox up and running in a hurry. While the documentation for both Blackbox and bbkeys is quite good, the novice might find it overly complex, especially for what the average home user wants from a window manager.

(Recently it seems as if the documentation has disappeared, save for the man pages. Hopefully this will be rectified sooner or later--because of this, I thought it a good idea to add the section on installing themes)

So, step one, get Blackbox. It was available here, but lately, it seems to be giving 404 messages. However, it can still be found on SourceForge here though that site is said to be iffy. Try to get it from there. I usually make a directory for my downloads in /usr/local/src. So, while this isn't really necessary, if you like the idea

mkdir /usr/local/src/blackbox

Save the downloaded file to that directory. I believe that at present it is available as tar.gz or tar.bz2. (There's probably an RPM as well, but I haven't looked recently.)

Assuming you've saved it to this /usr/local/src/blackbox directory as blackbox-x.x.tar.gz

cd /usr/local/src/blackbox
tar -zxvf blackbox-x.x.tar.gz
cd blackbox-x.x
make install
make clean
make distclean

The last two aren't 100 percent necessary, but are recommended by the program's author, especially if you've had a prior installation. (By the way, I've just saved you the trouble of reading the INSTALL file)

For FreeBSD this isn't necessary--simply install it from ports.

cd /usr/ports/x11-wm/blackbox
make install

(If you've downloaded the tar.bz2 rather than the tar.gz the differences would be, in RH

tar -jxvf blackbox-x.x.tar.bz2

In Slackware and some other distros that don't support the -j option (you'll know because if you try that command, you'll get unknown option -j)

tar -yxvf blackbox-.x.x.tar.bz2

If it still doesn't work, then

bunzip2 blackbox-x.x.tar.bz2 && tar -xvf blackbox-x.x.tar

From there, the rest of the installation is identical.

Starting blackbox

If you've been using another window manager, this will vary from distro to distro. In RH, for example, you'll have either an .Xclients or .Xclients-default file in the user's home directory. In other distros, you'll just have an .xinitrc. The quickest way to do this, if there is no .xinitrc file, is from the home directory of the user that will be using blackbox

touch .xinitrc
echo "exec blackbox" > .xinitrc
chmod 500 .xinitrc

If there is already an .xinitrc file, you can open it with your text editor--it'll probably only have something like start kde or whatever the command is for Kde or Gnome. Comment that out by putting a # before the line calling Kde or Gnome and insert

exec blackbox

You might also edit your /etc/inittab. You'll see lines like

# Default runlevel. The runlevels used by RHS are:
#   0 - halt (Do NOT set initdefault to this)
#   1 - Single user mode
#   2 - Multiuser, without NFS (The same as 3, if you do not have networking)
#   3 - Full multiuser mode
#   4 - unused
#   5 - X11
#   6 - reboot (Do NOT set initdefault to this)

Change that id:5:default to id:3:default which will tell your machine to boot Linux in text mode. You'll find that it boots more quickly than it does if you start it in graphical mode. You can then, after logging in type


and Blackbox will open up.

Right clicking on the screen will open up a pre-configured menu with some of the most commonly used programs. If you want to add programs to this menu, you open, with a text editor, the file

/usr/local/share/Blackbox/menu (note that Blackbox often begins with a capital B, though in in recent versions, this seems to have changed. Also, this directory varies, depending upon distribution and O/S--in FreeBSD for example, it's in /usr/X11R6/share/Blackbox/menu, or possibly blackbox/menu). If you go down the menu a bit you'll see lines like

[exec] (xterm) {xterm}

You can add items that you'd like available in that menu. For example, as I need to be able to input Japanese, I want kterm (an xterminal that allows me to read and input Japanese) in the menu. So, right under the xterm menu I add

[exec] (kterm) {kterm}

The middle entry, inside the ( ) is what you'll see in the menu. So, I could have written

[exec] (KTERM) {kterm}

and I would have seen, when right clicking on the screen, KTERM rather than kterm as a menu entry. The entry inside the { } is what actually calls the program, so there, one has to pay attention to upper and lower case.


One thing that some people don't like about blackbox is that it lacks certain keyboard shortcuts. For instance, one can't move between windows with the alt+ tab keys, but must focus on the window by using the mouse. To overcome this, there is a little program called bbkeys. Again, in FreeBSD it's in the ports collection, also under /usr/ports/x11-wm and in Linux one should download it here. I found that the RPM was only for an i686 platform, so again, I would go with the tar.gz file. One can, if they wish, do it as mentioned above with blackbox, make a directory

mkdir /usr/local/src/bbkeys

Download the tarball to that directory.

cd /usr/local/src/bbkeys
tar -zxvf bbkeys-x.x.tar.gz
cd bbkeys-x.x
make install

Now, open up your .xinitrc file and insert, above the line reading exec blackbox

bbkeys &

The next time you do a startx, you'll see an icon in the lower left saying bbkeys. Clicking on it will bring up the configurator.

In FreeBSD it brought up the graphic configurator, which is fairly self-explanatory--in Linux, however, it brought up a text based one that suggested you use the graphic one. However, it's really not necessary. Let us say, for example, you want to mimic Windows and have alt + tab move from window to window. You also want to have alt + F4 shut a window.

So, the first option is

Enter a key to grab.
Type in

Tab (note that the T is capitalized--when I didn't do that, it didn't work properly)

Next it says

Enter Modifier Name

If you want to use the alt key, type in


Mod1 is how bbkeys refers to the alt key. The Control key is Control and the shift key is Shift--the menu gives a few examples

Next you're asked to enter the action you wish performed, with a list of possible choices. In this case, we want NextWindow so we type it in as it is shown in the menu


The menu then repeats. So, this time, we want alt + F4 to close a window. Therefore

Enter a key to grab: F4 (note that you type in the letter F and the number 4)
Enter Modifier name: Mod1
Enter action to perform: Close

Now when we're prompted again, we type Q for quit. We now have a file in the home directory of the user called .bbkeysrc. The one we just made looks like:

KeyToGrab(Tab), WithModifier(Mod1), WithAction(NextWindow)
KeyToGrab(F4), WithModifier(Mod1), WithAction(Close)

If you run the configurator again, brought up by clicking on the bbkeys icon, it will overwrite this file with a new one. So, be careful--if you like your current bbkeys setup but think you might like to improve it, first back up the current one.

mv .bbkeysrc bbkeys.old

Then, if you aren't happy with the next one you make, you can always go back to the old one by typing

mv bbkeys.old .bbkeysrc

Remember, that until you're at the point where you want to manually configure your .bbkeysrc file, that you would have to go through the keyboard shortcuts you've already created. That is, running the configurator won't ADD commands to what you've already configured--it just makes a whole new file

After awhile, however, you might even find it quicker to edit the file manually--as you can see from the above example, it's relatively simple. Having done it quite often in vi, I find that it's probably quicker for me to do it manually.

A quick note--the latest version, that is available, at least, with FreeBSD if you upgrade your ports, seems far more sophisticated--I haven't played with it very much yet, but it looks as if it's going to be a complete manager for Blackbox--setting themes, etc.

Themes and backgrounds

After awhile, you might get tired of the default themes that come with Blackbox. Many people have created themes that can be downloaded--go to and you can find a variety of themes, most with their own background.

These are usually rather easy to install. You can do it my way, or your own--this is the way I do it because I'm relatively lazy and like to try to more or less organize things.

So, let's say I'm downloading a theme called theme. First, I make a directory to hold the tarball--I make it right in /usr/local/share/Blackbox. So

mkdir /usr/local/share/Blackbox/theme

I then download it into that folder and then cd to that folder

cd /usr/local/share/Blackbox/theme

In there I'll see a tarball, in our example, theme.tar.gz. I'll untar it

tar -zxvf theme.tar.gz

I've only done this with a couple of themes. However, the pattern should be similar enough for the reader to figure out any differences. Usually, you'll either see two new directories, styles and background or perhaps just the style file and the background image. So, let's say we now see in our theme directory, two subdirectories--one called styles, the other called backgrounds. In the styles directory is a file called theme and in the backgrounds directory is one called theme.jpg

First either copy or move the styles file into Blackbox's styles file--for that's where the main menu looks for styles

mv styles/theme /usr/local/share/Blackbox/styles/

Now, if you right click on the desktop and look at the styles submenu, you'll see that the style theme has been added. However, the background image won't appear. If you open up the theme file in a text editor, you'll see a final line something like

rootCommand: bsetbg -f ~/.blackbox/backgrounds/theme.jpg

This is showing you where this style will look for its background image. So, make the .blackbox/backgrounds directory in your home directory and put the style's background image there

mkdir ~/.blackbox
mkdir ~/.blackbox/backgrounds
mv backgrounds/theme.jpg ~/.blackbox/backgrounds

The ~ indicates your home directory. Now, if you right click on the desktop and choose the new theme entry, the background image will also appear.

If you like designing backgrounds, but don't know how to create a totally new style, you can easily add your own background to an existing style. First create your background image. Then put it somewhere--I usually put it where a Blackbox theme would, in .blackbox/backgrounds. You will probably have to create that directory

mkdir -p .blackbox/backgrounds

Now it depends upon what you have installed. If you have Eterm, you should have the Esetroot command. So, if I want my new background.jpg to be the background for the already installed Rancor style I open up (as mentioned above, this directory differs, depending upon distro and O/S--this is for FreeBSD) /usr/X11R6/share/Blackbox/styles/Rancor and go to the end of the file. If you're using vi then shift + g will take you to the end of the file. This is where you want to go. You'll see a line like

rootCommand: bsetroot -gradient interlacedflatcrossdiagonalgradient -from rgb:4c/04/03 -to black

You can comment that out or not, as you choose--I've found that it didn't make any difference. (It might in other styles, but I've only tried this with Rancor)

Add the line

rootCommand: Esetroot ~/.blackbox/backgrounds/background.jpg

This will work if you have the necessary libraries and such installed. The nice thing about Esetroot is that it will tile the picture--say my screen is at 1024x768 and the picture is 500x500--Esetroot nicely tiles it for me.

If Esetroot doesn't work, then you can try

rootCommand: bsetbg -f ~/.blackbox/backgrounds/background.jpg. In this case, the image has to be the same size as your screen--if I use the same 500x500 jpg it will be stretched, giving an odd effect. So, I would, in this case, use an image that is 1024x768. However, you can use the -t (for tile) option to let it tile over the screen. -ft seems to be an invalid option (in my experience) so, I change the rootCommand to bsetbg -t ~/.blackbox/backgrounds/theme.jpg and this works

If nothing happens, that probably means you're missing an image display program. One way to check this is to type, in an xterm

bsetbg -f ~/.blackbox/backgrounds/background.jpg

You may get messages that it's searching for a program to open the images, qiv, xv, etc. If it finds none of them, there will be a message giving suggested programs and their urls. In FreeBSD one can just go to /usr/ports/graphics and install one of these programs from there. In Linux, it will depend upon the distro--you might have it on the CD somewhere, or might have to go to the website and download and install one of them.

Once this is all done, if you now choose the Rancor style, you'll find that your background.jpg is thebackground

Lastly, there is the xsetbg command--this too will usually tile the image--again, I've had mixed results. For example, on a RH install, I couldn't get Esetroot or bsetbg to work--so, I tried xsetbg and it would give me the image, but wouldn't tile it--it also seemed to have trouble with gifs (as opposed to jpgs). The next day, not changing anything, I tried it again and images were tiled perfectly--so go figure. In another installation, it insisted upon the image being a bitmap. So, it seems to vary with each distro.

Well, that's about all there is to getting blackbox and bbkeys up and running to the point where you can add items you want to the menu, use basic keyboard shortcuts and install your own themes. Enjoy.