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