libXCB (X C Binding library)

XCB (X-protocol C-language binding) was intended to fully replace Xlib for X11: so far, XCB has gradually replaced some parts of it. Its purpose was to be more efficient and to be easier to program. X11 is a protocol. Xlib and XCB are both API's and library sets.

Xlib (also called libX11) is too low level for most graphical programming needs, it: has features not commonly used, had lack of compile checks, and was complicated to program with. Simple programming tasks needed excessive coding in Xlib. Its purpose was also too wide range for both applications and toolkits.

XCB is in C: it uses C header files, and it requires knowledge of C programming. XCB's library is libxcb, and its header is xcb.h. To compile programs that use XCB, they must be linked to relevant XCB's libraries. xcb-proto only installs header files.

XCB is POSIX compliant. This API library is also thread-safe, and it has better error handling than Xlib.

Parts of Xlib were replaced by parts of XCB. Xtrans (X Transport Interface), a low level part of Xlib, was replaced with XCB. Also, Xlib can receive calls to XCB through a transport layer from X11. XCL was an emulation layer from XCB (as a proof of concept, which some parts which were kept for a newer library: updated explanation below) to receive instructions from Xlib outputs. Many programs originally written for Xlib, are partially implemented in XCB, and receive mixed instructions for these two libraries. Parts of XCB have been available within replaced parts of libX11 since 1.2.0 (this became default since 1.4.0). LibX11 version 1.7.2 is currently in ports, as of this writing.

Previously XCB used M4 based protocol description language. This was replaced with XML in 2004. XCB extensions are simplified, as all each one needs is an XML description.

There is a lack of documentation for XCB, but enough information on it can be found in X11 documentation and in the programming notes.

Ports tree applications
In the ports tree: x11-wm/mcwm and x11-wm/bspwm are window managers that are built on XCB. x11-wm/compiz is a compositor that is built on XCB. Other ones: x11-wm/chamfer, x11-wm/i3, x11-wm/i3-gaps, x11-wm/phoc, x11-wm/spectrwm, x11-wm/sway, x11-wm/wayfire and x11-wm/awesome.

x11/thingylaunch can be compiled with XCB instead of Xlib. x11/lemonbar is in XCB. x11/polybar is another bar, but it has more dependencies and options. Other programs in the ports tree that use XCB and not Xlib are few: x11/xtitle, x11/xlsatoms, x11/xcbautolock, x11/ly. Most other programs that use xcb, instead of xlib, rely on QT5 or Rust.

Last edited:
x11-wm/mcwm is a minimalist window manager that requires a terminal emulator to be run with it, and x11-wm/bspwm is a tiling window manager with binary behavior which by default uses x11/sxhkd for keyboard inputs. Both of these window managers use bsd-like licenses.

MCWM has a low residential RAM footprint of about 2.6MB. Xterm adds about 14MB to that. BSPWM uses about 3.4MB for resident memory. SXHKD adds about 2.9MB.

Common libraries and their ports between MCWM and BSPWM:
BSPWM additionally uses:

Xinerama adjusts maximizing windows on multi-monitors. When it's not compiled in to other window managers, a maximized window will take up all of 2 screens.

EWMH and ICCCM are compatibility standards for window managers.

XMU and Xext aren't needed for XCB. libXRendr is traditionally a dependency of XFT for fonts on Xlib, but is now obsolete. XFT may not be relevant for XCB dependencies.

Ports that rely on x11/xcb-util:

Screenshots & Configuration

Screenshot of MCWM which uses XCB, and of xterm. bgs or xsetroot are needed to set the background. This image is from the thread: Thread screenshots-of-bsd-window-managers-for-x11.81505/. From .xsession/.xinitrc, this window manager requires a different way to start than other window managers: xterm is started last with exec, and the ampersand goes after mcwm:
mcwm &
exec xterm -bg black -fg white +sb -uc -bc


BSPWM screenshots by tedbell & rigoletto@ from Thread freebsd-screen-shots.8877. (The image on the left uses Polybar and dzen. Both images use Conky.)

BSPWM needs bspwmrc copied from /usr/local/share/examples/bspwm/ to ~/.config/bspwm/.
To use SXHKD, copy /usr/local/share/examples/bspwm/sxhkdrc to ~/.config/sxhkd/.

Edit .xsession or .xinitrc to:
sxhkd &
exec bspwm

Cairo graphics library can be compiled with XCB turned on, and Xlib and glib turned off. It is under both LGPL and MPL licences. Cairo is nice, but it is too heavily convoluted into Gtk.
History of XCB transition libraries
XCL (Xlib Compatibility Layer) was a proof of concept for replacing Xlib code with XCB code while maintaining compatibility with programs that call Xlib. xcl.h is obsolete as a standalone library. A previous and obsolete instruction said to replace Xlib.h with xcl.h. Another past instruction said to use --with-xcb for compiling Xlib. These instructions for using the XCL library have been obsolete since 2014.

Xlib/XCB (Xlib-xcb.h) has replaced XCL, and this library contains XCB, Xlib and some XCL library code. The library X11/Xlib-xcb.h is installed with x11/libX11. The use of Xlib-xcb.h replaces xcl.h, and it can be used in place of Xlib.h and xcb.h. Using this library allows mixed calls to be made to transition porting to XCB.

Separately from mixed calls, XCB code has replaced Xtrans (X Transport Interface) for the low level transport layer in current default Xlib. Xorg or libX11 installed from ports has the directory /usr/local/include/X11/Xtrans/ installed from x11/xtrans. Xtrans appears to still be used only for parts of its header.
Transitioning to XCB
Xlib-xcb.h and Xlib.h are both installed by x11/libX11. The current instruction is to replace X11/Xlib.h with X11/Xlib-xcb.h in source files written in C where transitioning to XCB will be attempted. In mixed calls, Xlib code gets priority over XCB code. Alternatively, x11/libxcb is for C code that's written purely in XCB. Additional ports related to libxcb have more features than that of Xlib/XCB.
XCB applications and additional libraries:
XCB window managers:
XCB directory of base libraries
Latest on XCB
Last edited:
XCB on XWayland
Weston ( is a sample/showcase compositor and libweston is its related application library for building applications and compositors. These are both maintained by libweston is compatible with libxcb through XWayland. Unclear if this application library has builtin libx11 functionality.

wlroots (Wayland Roots), maintained by (, when used with XWayland has a dependency on libxcb, so doesn't have direct support for the older libx11 API. A handful of compositors are built on top of wlroots' library.

wlc is a defunct compositor and application library that has been replaced by wlroots, wlc had support for libx11 and libxcb.

XWayland in FreeBSD's portstree depends on libX11 and not directly on libxcb, though libx11 depends on libxcb. It appears as if compositors on wlroots are intended to be in xcb. From XWayland, applications are intended to be compatible from both x11 and xcb.

libXCB makes sense as a common library to be used on XWayland across varying Wayland compositors and their libraries for applications. It may make more sense for window managers to be ported to a Wayland compositor library.

Further reading
x11-wm/ittywm fork of tinywm in libxcb
x11/jbxvt clone of xvt terminal in libxcb

ittywm and jbxvt running together:
  1  20    0    13M  2740K select   3   0:00   0.00% jbxvt
  1  33    0    13M  2308K select   2   0:00   0.00% ittywm
x11-wm/mcwm and jbxvt running together:
  1  20    0    13M  2564K select   1   0:00   0.00% jbxvt
  1  23    0    13M  2528K select   3   0:00   0.00% mcwm

Comparison to tinywm and xvt running together:
  1  20    0    18M  5708K select   3   0:00   0.20% xvt
  1  34    0    14M  3376K select   1   0:00   0.00% tinywm

jbxvt still calls for libx11 and relies on it for compiling. The headers call for it, even if the other sourcecode doesn't need it.
Window Managers in XCB, with non-viral licenses
  • x11-wm/spectrwm - Dynamic window manager based on DWM, but doesn't require hacking C to adjust settings. In XCB for features available in its library. dwm-xcb is another XCB port of DWM, not in ports.
  • x11-wm/i3 - Tiling window manager in XCB, which merged with its former XCB fork i3-gaps.
  • x11-wm/bspwm - Tiling window manager in XCB, based on binary space partitioning.
  • x11-wm/ittywm - Based on TinyWM, but in XCB. Lighter on resources than its predecessor.
  • x11-wm/mcwm - Similar key management and window functionality to TinyWM, intended for use with terminal, but can also be used with hotkey programs. Has good features for multiple monitor use. mcwm is inspired by ctwm, tinywm and evilwm (based on 9wm).
  • x11-wm/fswm - Full screen window manager that is an XCB alternative to AntiWM. It is also a bit lighter on resources than AntiWM.
  • 9wm-xcb - Rudimentary window manager based on 9wm. Calm Window Manager (CWM) used in OpenBSD and its derivative EvilWM are based on 9wm, which aren't in XCB. Not in ports.
  • MonsterWM-XCB & FrankenWM - XCB window managers based on DWM and MonsterWM. These have plenty of tiling layout options, plus floating mode and full screen mode. Require editing a header file in C and recompiling to configure settings. FrankenWM is also based on MonsterWM-XCB, and additionally based on 2bwm and mcwm. FrankenWM has a base of use on ArchLinux. MonsterWM-XCB has fewer lines of code than MonsterWM, and way fewer than FrankenWM. FrankenWM is updated more regularly.
  • mmWM - Modern Minimalistic Window Manager is a dynamic window manager not in ports. Based on mcwm, 2bwm, MonsterWM-XCB and FrankenWM. It has lots of FrankenWM features stripped out, and other features added in. For instance, it isn't a tiling window manager. Also requires editing a header file and recompiling to configure settings. mmWM has two versions.
  • xwm (not original xwm) - Intended for single monitor setups. It is intended to be extensible for more features to be added through forks.
The above list matches nearly all types of window managers: lightweight, dynamic, command line/terminal, tiling, full screen, and floating. This list is refined to give a better understanding of differences and similarities of function between XCB window managers.

To start FSWM, use fswm xterm, which exec /usr/local/bin/fswm xterm can be added in the last line of .xsession or .xinitrc. A few other terminal emulators can be used in place of xterm, such as xvt. ctrl-alt-t will start a new window, if the terminal emulator specified in start up. ctrl-alt-tab cycles through screens. ctrl-alt-delete exits the window manager.

FSWM can optionally be used with x11/thingylaunch, while AntiWM has troubles using it. Shortcuts can be customized by using x11/sxhkd for use with thingylaunch on fswm, while antiwm needs editing a c file and reconfiguring it to customize it. FSWM is slightly lighter than AntiWM. The SIZE of them is similar at 13M for FSWM to 14M for AntiWM. The RES of FSWM is about 2316K, compared to 3460 for AntiWM. Other programs and window managers in XCB have noticeably less usage than their libX11 counterparts.

In one past instance, FSWM once functioned similarly to MCWM, but uncertain if it's based on it. Nothing in the source seemed to have changed since then, so perhaps the program interacted with other dependencies of other window managers on the desktop, or a configuration was different. It behaves as full screen treating both monitors as 1 combined screen, when in a past instance, it ran more like MCWM, treating two monitors as two separate screens of their own.

Xinerama allows treats each screen as separate, rather than combining into one large screen. The xinerama library for XCB is included in x11/libxcb. The other implementation of Xinerama has its own package and is in libx11. There's no evidence that fswm calls the libx11 implementation of Xinerama. MCWM treats two monitors as their own screen.

Other WM mentions
2bwm is based on mcwm intended for more features which are implementation incomplete. FrankenWM and mmWM are based on 2bwm.

xcwm (C Window Manager, not Calm Window Manager) - according to the description, only has full screen layout, hasn't been maintained in years.

Command utilities
The XCB programs x11/sxhkd for hotkeys and x11/thingylaunch as a command launcher improve usage, functionality and navigability of window managers. These can help when being unfamiliar with using a new window manager.

A terminal emulator is also good as many window managers can be used like intended with mcwm, where the terminal emulator is started last, which exiting this also closes the window manager session. x11/jbxvt is a terminal emulator in XCB which is lighter than XVT, xterm and sterm. Changing the font requires inserting the complete argument on the command line, for instance, jbxvt -F "-*-courier-medium-r-*-*-18-*". Unfortunately, jbxvt crashes often.

For comparison of resource use of these terminal emulators, top | egrep "(PID|xvt|xterm|st)":

jbxvt        13M      2300K
xvt          18M      5456K
st           22M      10M
xterm        27M      16M
alacritty   264M     183M
An interesting overview; thanks for sharing :)

I never really looked into xcl.

libXCB makes sense as a common library to be used on XWayland across varying Wayland compositors and their libraries for applications. It may make more sense for window managers to be ported to a Wayland compositor library.
I wonder if Xlib/XCB APIs could also be used to mostly abstract things in native Wayland.

One of the main issues for Wayland adoption is that there is no standard library. You just about have a wayland client library but a shim or drop in replacement of Xlib could help port a number of existing programs.

There used to be Xlib shims for DOS for this kind of thing and I think (???) Wayland is meant to be an improvement to that.
It would depend on what the compositor supports. The compositor WLRoots by looking at its dependencies, when used with XWayland may already be an XCB shim. Everyone reports that X programs don't work on it, perhaps because no one has tested XCB only programs on it. The older Weston compositor was meant to work with libx on top of XWayland, but Weston is considered primitive as many compositors are considered more modern. Weston is still good as a testing ground for trying traditional X programs on XWayland, where other compositors don't support libx and libxcb. There will always be room for a compositor to have an XCB shim, as the way compositors are meant to work on top of Wayland.

In short, WLRoots can be tried for XCB only programs on XWayland, and the Weston compositor can be experimented with for libx programs on XWayland. Additionally, there were reports that X programs worked on Weston, but more recently, claims have been that nothing works on either WLRoots or Weston on XWayland. Then, there's room for other compositors to come into existence to make up for if these come up short.

I never really looked into xcl.
Parts of XCB have become a lower layer of Xlib, replacing only that part, and not the upper layers of it. XCL was an older implementation of XCB's lower layers that have replaced the lower layers of libx. In clarity, now the lower layers of libx are in XCB, and XCL was an obsolete implementation or testbed of that.

Perhaps there is a lack of a compositor or XWayland layer that goes from the newer implementation of xlib which use the lower parts of XCB as a base layer.

There aren't many programs in pure XCB that are in C. KDE, which is in C++, took in XCB as an underlying library layer. Rust has more programs that use the XCB library than that are in C itself. It was frustrating to see that XCB started off with some momentum, then seeing programmers write how they'll rewrite a program made in XCB back in libx11, because of lack of documentation or because they were unfamiliar with programming with XCB.

Terminal emulator jbxvt (x11/jbxvt) is mostly in XCB, but it has a small amount in Xlib, and it also crashes a lot.

One of the main issues for Wayland adoption is that there is no standard library.
The compositor or the toolkits would be a substitute for that standard library. The toolkits (as shims) would be GTK, KDE or SDL. Wayland was intended for people to learn a particular toolkit than programing graphical applications to Wayland directly.

One issue, is that when using a toolkit, sometimes, programmers go around the toolkit and directly to a lower layer such as xlib, as you can see when looking at how dependencies are linked and header calls. Still, I give them credit for getting that far, and at least having or keeping many layers within the toolkit or other efficient implementation. I believe it's because they default into working with what's familiar for them, and they're not changing existing parts in the more modern library or toolkit to the lower level library.

Either SFT or Fonts-for-XCB would have to be ported for fonts in XCB. It looks like SFT may be an XCB replacement for Xft (x11-fonts/Xft). These types of fonts are required a toolkit to have internationalization support, and are part way for additional handicap accessibility support. Without extended fonts and an option for accessibility support, a graphical toolkit is considered obsolete. SFT may be the enough for fonts, at least as simply an Xft replacement: lacks documentation. I'm not sure if the source code of Fonts-for-XCB ( is excessive or needed to cover more language texts.

I would like to see x11-toolkits/libxaw3dxft ported to XCB for X, then also ported to Wayland. The other xaw implementations are considered obsolete, because they lack extended font support required for internationalization and accessibility.
Status on XCB fonts from source repositories, perhaps for Simple FreeType, may be incomplete for fonts in XCB, at least the Makefile is incomplete. It's perhaps intended as a x11-fonts/libXft replacement. It asks for the same dependencies as libXft and has a similar name. has two forks. claims to have errors corrected, but is abandoned as code moved on to a seemingly unrelated project. is a fork where C code is stripped down to one header file.