Cpp-Blackboxwm: A window manager for X11


Package blackbox-0.77 was released under MIT license 2021-05-11.

This is a fork of the original blackbox CVS that is on Sourceforge. This fork is hosted on GitHub. What it includes is all changes made on the official blackbox CVS repository on branch blackbox-0_70_2cvs, as well as patches collected from pdl-linux, Debian, the blackbox bug list, other GitHub forks. It also includes enhanced EWMH/ICCCM compliance.


This is the blackbox-0.77 package, released 2021-05-11. This release, and the latest version, can be obtained from GitHub, using a command such as:

$> git clone https://github.com/bbidulock/blackboxwm.git

Please see the NEWS file for release notes and history of user visible changes for the current version, and the ChangeLog file for a more detailed history of implementation changes. The TODO file lists features not yet implemented and other outstanding items.

The file COMPLIANCE lists the current state of EWMH/ICCCM compliance.

Please see the INSTALL file for installation instructions.

When working from git(1), please use this file. An abbreviated installation procedure that works for most applications appears below.

This release is published under the MIT/X Consortium license that can be found in the file LICENSE. This release is published under GPLv3. Please see the license in the file COPYING.

Quick Start

The quickest and easiest way to get blackbox up and running is to run the following commands:

$> git clone https://github.com/bbidulock/blackboxwm.git blackbox
$> cd blackbox
$> ./autogen.sh
$> ./configure
$> make
$> make DESTDIR="$pkgdir" install

This will configure, compile and install blackbox the quickest. For those who like to spend the extra 15 seconds reading ./configure --help, some compile time options can be turned on and off before the build.

For general information on GNU's ./configure, see the file INSTALL.

Configuring blackbox

The next thing most users want to do after installing blackbox is to configure the colors, fonts, menus, etc. to their liking. This is covered by the files README, README.menu and README.style. These files give detailed information on how to customize your new window manager.

Included utilities

Currently, the only included utilities are a program named bsetroot(1) and a script called bsetbg(1). bsetroot is a replacement for xsetroot(1), minus a few options. The difference between xsetroot(1) and bsetroot is that bsetroot has been coded for multiple screens (e.g. multi-headed displays), where as the stock xsetroot(1) is not. The bsetbg script acts as a wrapper for most of the popular programs used to set background pixmaps, making it possible for styles to provide a machine-independent rootCommand.

Third-party utilities

With the start of the 0.60.x series blackbox no longer handles any keyboard shortcuts; instead it supports a communication protocol which allows other programs to handle these and related tasks. If you'd like to be able to use keyboard shortcuts with blackbox, bbkeys(1) can provide you with all the previous functionality and more.

If you're looking for a GUI with which to configure your blackbox menu and/or styles, check out bbconf(1). bbconf(1) is a QT program that does just that, as well as providing a GUI for editing your key bindings for the above mentioned bbkeys(1).


Read the manual page after installation:

man blackbox


Report issues on GitHub here.


  • Multi-monitor support: only use active monitor with maximize and full-screen commands
    Multi-monitor support: only use active monitor with maximize and full-screen commands

    Apr 6, 2017

    I have two monitors. When I maximize a window or make it full-screen, it occupies both monitors (i.e. the entire virtual desktop/screen). This is way too big, so I'd prefer that the window only occupy one monitor. Other window managers get this right already, so I'm guessing there's some protocol/extension that isn't implemented in blackbox.

    Perhaps this issue is a feature request.

    I'm currenty using blackbox version 0.72, commit 8c9e2af7d34ea076f684ce47d8e4f0268b054c71.

  • Exit Full Screen
    Exit Full Screen

    Sep 11, 2019

    Is there a way to exit full screen mode?

  • segfaults when fonts aren't found
    segfaults when fonts aren't found

    Apr 22, 2020

    Please forgive me if my github etiquette is lacking. This is my first time filing an issue.

    With version 0.76 there seems to be some problems if fonts are missing.

    In Font.cc on lines 450 and 462, if the font specified in the style file is not found, NULL pointers are dereferenced causing segfaults. Wrapping those and returning 0 if the pointers are NULL leads to another segfault.

    #0 0x00007effcf9671b0 in XmbTextExtents () from /usr/lib64/libX11.so.6 #1 0x00000000004443b0 in bt::textRect (screen=, font=..., text="m\000\000\000:\000\000\000m\000\000\000m\000\000\000m\000\000\000m\000\000\000 \000\000\000 \000\000\000 \000\000\000 \000\000\000m\000\000\000:\000\000\000m\000\000\000m\000\000\000m\000\000\000m\000\000\000") at Font.cc:398 #2 0x0000000000414374 in BScreen::updateGeomWindow (this=0x1e8a6c0) at ../lib/Display.hh:84 #3 0x000000000041ba24 in BScreen::reconfigure (this=0x1e8a6c0) at Screen.cc:522 #4 0x000000000043aea0 in std::mem_fun_t<void, BScreen>::operator() (__p=, this=) at /usr/include/c++/9.3.0/bits/stl_function.h:1211 #5 std::for_each<BScreen**, std::mem_fun_t<void, BScreen> > (__f=..., __last=0x1ea1d18, __first=0x1ea1d10) at /usr/include/c++/9.3.0/bits/stl_algo.h:3876 #6 Blackbox::timeout (this=0x7ffc6f775460) at blackbox.cc:402 #7 0x000000000043e457 in bt::Application::run (this=0x7ffc6f775460) at Application.cc:300 #8 0x000000000040a0f8 in main (argc=1, argv=0x7ffc6f7758e8) at main.cc:167 (gdb)

    The Font.cc:398 might be off a little, as I had been editing that file to check for NULL pointers, but those /should/ all be after that line leaving this one unaffected.

    I was going to debug it further and hopefully be able to submit a patch, but that may be a few days off; I haven't really dug into the blackbox source since 0.65. Right now it's easier for me to make sure the right fonts are present.

  • Blackbox Needs To Step Into the 21st Century - PLEASE!
    Blackbox Needs To Step Into the 21st Century - PLEASE!

    May 24, 2020


    I personally think Blackbox aka BB is the best WM for Linux when it first started by ‎Bradley.

    Then Openbox and I'm sure life for ‎Bradley came along, and BB died out.

    1. Blackbox use to have a list of themes on box-look.org as if the people who are running this site removed everyone of them, I mean WTF! PLEASE contact them and see about getting BB themes put back on.

    2. Yes tint2 doesn't play nice with BB, but can you PLEASE contact o9000, the developer and ask him to please better support BB, that you are maintaining.

    3. Styles/Menus of BB are way to Dated, like 1990 Linux, and for all the old died hards, ok, I said I used BB in the beginning and I loved it, but, it would be nice to modernize the style and menu.

    I'm not a developer or coder, if I was, I'd do all these things, I also don't have the time, I look to those like you to do these things, if you have the time, it would be greatly appreciated.

    Openbox development is dead, and people think because everything works perfect, sorry software has bugs and there's no such thing as perfect, and for other personal reasons, I'd rather not use Openbox, but BB is still to outdated and not with the times.

    I know using the small window managers of Linux is not the popular choice, most use KDE, or Gnome, Cinnamon, XFce, etc...

    BUT I do know there are still alot of people out there like me that do like the small window managers, because those of us that run Linux and know how to run Linux don't need bloated desktops, and soon come to realize with all that bloat comes issues and bugs.

    I'm a Slackware Geek, and I say, if you need to use KDE or Gnome, then stick to Windows!

    Openbox and Blackbox is all a Geek needs! LOL... Or for the Tilling Geeks, i3...


  • BB-conf wont compile
    BB-conf wont compile

    Jun 9, 2021

    bbconf doesn't work because of dependencies that are outdated and aren't available anymore. I'm not very technically skilled so I'm unable to find out which ones.

  • Feature request: Add configure option to use Mod4 (or whatever) instead of Mod1 for window moving and resizing
    Feature request: Add configure option to use Mod4 (or whatever) instead of Mod1 for window moving and resizing

    Sep 24, 2021

    After a lot of Googling for how to use the Windows/Super key instead of Alt for moving windows around, I finally decided to check the source code and saw that Mod1 is hardcoded (at least I think it is): https://github.com/bbidulock/blackboxwm/blob/7d9bb9db18a940dc70ee0cc550c11931784b4271/src/Window.cc#L1862-L1872

    It would be nice to be able to change that from some rc value like I have been able to in other window managers. I am also used to Win+middle button for resizing, so I guess being able to change the mouse button used in the above code using an rc file value would be good too :)

  • autogen.sh doesn't work correctly with all gettext versions (e.g. 0.20.1)
    autogen.sh doesn't work correctly with all gettext versions (e.g. 0.20.1)

    Jun 17, 2019

    Two related things here. I can see that commit "handle gettext" https://github.com/bbidulock/blackboxwm/commit/f57b1019c32082a20e379186475d588ef5d8c784 added some sed to only match the first three parts of a gettext version number, presumably to work around the fact autopoint would fail to find infrastructure files for "". Unfortunately, this doesn't work with gettext 0.20.1, which is the same situation.

    I also don't follow in general why it's necessary to override the gettext version required for a non-developer build invocation? (In downstream packaging for pkgsrc.org, I've just commented out those particular lines for now. https://github.com/NetBSD/pkgsrc/commit/29e0ba461fe0f366d3763fbb661dc530c4f76ee0.)

  • Moving a window generates a backlog of move commands with high-speed mice
    Moving a window generates a backlog of move commands with high-speed mice

    Apr 6, 2017

    I'm using a Logitech G400 mouse, which generates mouse input at 1000Hz. Apparently the more typical rate is around 100Hz. This mouse generates noticeably more X11 events (e.g. run xev | nl).

    Using Blackbox, when I move a window, there is a substantial lag from moving the mouse pointer and the window itself moving. Presumably there is a message/event queue somewhere with move commands in it, and some(?) applications aren't able to keep up with the move commands.

    With a slower-speed mouse, this problem doesn't happen.

    Counter-intuitively, window resizing isn't affected.

    It doesn't matter whether I use Alt-mouse or click the title/resize-box.

    This problem does affect other window managers (e.g. xfwm4, but I also saw the problem with MATE and GNOME Flashback). Sometimes enabling compositing seems to fix the issue. I hacked around the problem in xfwm4 by adding rate limiting. I also wrote my own alternative to altdrag on Windows, where I instead fixed the problem using synchronous move/resize operations on a dedicated thread, driven by a command buffer where I collapsed subsequent move/resize commands.

    I might just give up and find a slower mouse.

    Blackbox version: 0.72, commit 8c9e2af7d34ea076f684ce47d8e4f0268b054c71.

    YouTube video of the issue: https://www.youtube.com/watch?v=mwBH_AkhW_Q&feature=youtu.be

  • Handbrake Gui Flickers In Blackbox
    Handbrake Gui Flickers In Blackbox

    Jan 30, 2016


    My Specs; Slackware 14.1 x86_64 Blackbox 0.71.1 nvidia-driver-352.63 xorg-server-1.14.3 handbrake 0.9.9

    I'm not sure what's causing this, I've never seen this before, only in Blackbox, the original 0.70.1 and your fork.

    When I start handbrake the right side of the window flickers really bad.

    I have compton the composite manager, but this happens with it running, or not.

    I created a video so you can watch this.


  • Possibly A Few Good Patches?
    Possibly A Few Good Patches?

    Jan 30, 2016

    I was looking through the patches applied, and I found these others online I didn't notice added, not sure if any are needed...

    Please check if you might need these, I'm not sure if any are useful.

    bbdock.patch https://gist.github.com/Geyup/e7be8e57aa546b854ec7

    asneeded.patch https://gist.github.com/Geyup/75d8a3e994999e87f665

    configure.patch https://gist.github.com/Geyup/61fa53b66f3627578f9d

    fix-spelling-errors.diff https://gist.github.com/Geyup/e99c429ce8b6a3bd508e

    focus.diff https://gist.github.com/Geyup/a32d45c94f7ab3b4c1c7

    manpage-tidyup.diff https://gist.github.com/Geyup/dc4c972a44333f9ae505

    This one below really caught my attention, because when using conky and you click on 'Restart' in the menu, conky will then redraw over itself creating what looks like multiple instances and it looks like a mess. I applied the patch and it worked! It appears there are argb issues without the patch.

    argb-visual.patch http://www.t2-project.org/packages/blackbox.html

    There is also a problem when using a composite manager, I use compton, when switching workspaces the numbers on the toolbar don't change, this patch fixes that.

    workspace-label.patch http://www.t2-project.org/packages/blackbox.html

  • Bugs Releated To Tint2
    Bugs Releated To Tint2

    Jan 30, 2016


    My System Specs; Slackware 14.1 x86_64 Blackbox 0.71.1 tint2 0.12.7

    Tint2 is back in active development and I hope you can please improve support for it.


    I opened a ticket asking for support for the original Blackbox;


    According to the developer his words;

    ** Tint2 does not use custom code for every WM that is out there; instead, tint2 assumes that the WM implements a specification called EWMH, also called NetWM. This describes how the window manager interacts with other applications, such as the panel.

    A lot of WMs implement this specification to the letter. Openbox, Fluxbox, Kwin, XFCE, GNOME and probably others. As a result tint2 works perfectly fine with all of these without needing any custom code. **

    This report I opened was with the original Blackbox 0.70.1, but since you've forked and updated I see one improvement, the numbers now appear in the tint2 panel. :)

    These are the few issues I still have.

    1. I had to change the option disable_transparency = 1 to use pseudo transparency. Using = 0 doesn't work for true transparency, can Blackbox work with true transparency?

    2. Tint2 with the default setting of, panel_margin = 0 0 will not allow tint2 to sit at the bottom of the screen, this setting works in Openbox. I had to change it to, panel_margin = 0 -33 to push tint2 to the bottom of the screen. The tint2 developer suggested to see how screen margins are configured in blackbox.

    3 Releated to what appears maybe screen margins again, when I maximize the size of a window, it fills the entire screen and goes behind tint2, it does not sit on the top of tint2 like it should.

    4. If I have a window minimized to tint2, and then click on another workspace section of tint2, the application follows and jumps over to the next workspace too, but if the window is not minimized, this doesn't happen.

  • Font rendering issue on Alpine Linux
    Font rendering issue on Alpine Linux

    Dec 2, 2018

    I compiled successfully blackbox on Alpine Linux but it appeared to has a font rendering issue which I couldn't figured out why.

    Compile environment:

    Gcc 8.2 x86_64
    CFLAGS="-Os -fomit-frame-pointer"

    Compile steps:

    ./configure --prefix=/usr --mandir=/usr/share/man --disable-nls

    Linking status:

    $ ldd /usr/bin/blackbox
    	/lib/ld-musl-x86_64.so.1 (0x7f4e8e57c000)
    	libXft.so.2 => /usr/lib/libXft.so.2 (0x7f4e8e314000)
    	libXext.so.6 => /usr/lib/libXext.so.6 (0x7f4e8e104000)
    	libX11.so.6 => /usr/lib/libX11.so.6 (0x7f4e8dfe1000)
    	libstdc++.so.6 => /usr/lib/libstdc++.so.6 (0x7f4e8de8c000)
    	libgcc_s.so.1 => /usr/lib/libgcc_s.so.1 (0x7f4e8de78000)
    	libc.musl-x86_64.so.1 => /lib/ld-musl-x86_64.so.1 (0x7f4e8e57c000)
    	libfontconfig.so.1 => /usr/lib/libfontconfig.so.1 (0x7f4e8dc3e000)
    	libfreetype.so.6 => /usr/lib/libfreetype.so.6 (0x7f4e8d98e000)
    	libXrender.so.1 => /usr/lib/libXrender.so.1 (0x7f4e8d784000)
    	libxcb.so.1 => /usr/lib/libxcb.so.1 (0x7f4e8d55e000)
    	libexpat.so.1 => /usr/lib/libexpat.so.1 (0x7f4e8d53b000)
    	libuuid.so.1 => /lib/libuuid.so.1 (0x7f4e8d335000)
    	libbz2.so.1 => /usr/lib/libbz2.so.1 (0x7f4e8d128000)
    	libpng16.so.16 => /usr/lib/libpng16.so.16 (0x7f4e8cefa000)
    	libz.so.1 => /lib/libz.so.1 (0x7f4e8cce3000)
    	libXau.so.6 => /usr/lib/libXau.so.6 (0x7f4e8cae0000)
    	libXdmcp.so.6 => /usr/lib/libXdmcp.so.6 (0x7f4e8c8da000)
    	libbsd.so.0 => /usr/lib/libbsd.so.0 (0x7f4e8c6c8000)