picom: an X11 compositor with animation support, built with meson

The problem picom solves on a bare X11 session

An X server without a compositor draws windows directly into the framebuffer. There is no off-screen buffer per window, so effects that need the previous frame, such as fading, shadows or blur, have no place to read from. picom is a compositing manager that takes over that job: it redirects window contents into off-screen storage and composites the final image itself. The README describes it plainly as "a compositor for X, and a fork of Compton".

The intended user is someone running a window manager rather than a desktop environment. The topics attached to the repository include compositor, compton, linux, x11, xcb, xcompmgr and xorg, which is the vocabulary of that audience. If you run GNOME or KDE, a compositor is already running and picom would be redundant or conflicting. If you run i3, dwm or a plain Xfce session, picom is the piece that supplies the visual effects those window managers deliberately leave out.

One caveat is printed in the README itself: "This is a development branch, bugs to be expected". The default branch is next, so anyone cloning the repository without specifying a branch lands on the development line, not on v13, the release published on 2026-02-07.

How picom composites: XCB, damage tracking and the render path

picom is written in C and talks to the X server through XCB. The dependency list is the clearest map of the architecture. It needs xcb-composite to redirect window contents off-screen, xcb-damage to learn which regions of a window changed, xcb-render and xcb-renderutil plus pixman to blend the result, xcb-xfixes and xcb-shape for window geometry and shape handling, and xcb-present and xcb-glx for the presentation and GL paths. libev drives the event loop, uthash provides hash tables for the internal window bookkeeping, and libconfig parses the configuration file.

The data flow follows from those pieces. The compositor selects for damage events, receives notifications when a window's pixels change, repaints the affected region into its own buffer, and presents the finished frame. Optional components sit on that path: libGL, libEGL and libepoxy enable the OpenGL backend, libpcre2 enables regex-based rules, and libdbus exposes control over D-Bus. Each of these can be removed at build time, which is a deliberate trade of features for a smaller dependency footprint.

The animation support mentioned in the repository description is the addition on top of what Compton did. The README does not document the animation configuration keys, so the place to look is the sample configuration shipped in the repository root, picom.sample.conf, and the man pages under man/.

Installing picom and running it for the first time

The README gives no package installation instructions. It goes straight to building from source, so the commands below are the ones it documents. On Debian-based distributions, the dependency list is long and the README spells it out:

libconfig-dev libdbus-1-dev libegl-dev libev-dev libgl-dev libepoxy-dev libpcre2-dev libpixman-1-dev libx11-xcb-dev libxcb1-dev libxcb-composite0-dev libxcb-damage0-dev libxcb-glx0-dev libxcb-image0-dev libxcb-present-dev libxcb-randr0-dev libxcb-render0-dev libxcb-render-util0-dev libxcb-shape0-dev libxcb-util-dev libxcb-xfixes0-dev meson ninja-build uthash-dev

On Fedora the README lists a different set, including dbus-devel, libconfig-devel, libev-devel, libX11-devel, libxcb-devel, libGL-devel, libEGL-devel, libepoxy-devel, pcre2-devel, pixman-devel, uthash-devel, xcb-util-image-devel, xcb-util-renderutil-devel, xorg-x11-proto-devel and xcb-util-devel. The build itself is two commands:

meson setup --buildtype=release build
ninja -C build

The README states that the built binary can be found in build/src, and that installing is a third command:

ninja -C build install

The default install prefix is /usr/local and can be changed with meson configure -Dprefix=<path> build. If your libraries live outside the default search path, for example under /usr/local/, the README says meson will not find them unless you set CPPFLAGS and LDFLAGS when running meson. It gives FreeBSD as the example:

LDFLAGS="-L/usr/local/lib" CPPFLAGS="-I/usr/local/include" meson setup --buildtype=release build
ninja -C build

For a first run, the repository root contains picom.sample.conf, which is the configuration template to copy and edit. The README does not document the command-line flags for launching it, so check the man pages under man/ before assuming a flag exists.

Where picom is the wrong choice

The most direct limitation is the display server. picom is an X11 compositor built on XCB and xcb-composite. On a Wayland session it has nothing to attach to, because the Wayland compositor already owns the rendering of client surfaces. If you have moved to Sway, Hyprland or a GNOME Wayland session, picom is not the tool, regardless of how the configuration is written.

The second limitation is the branch situation. The README labels the development branch as bug-prone, and that branch is the repository default. Anyone building from a fresh clone is building the development line. The releases list shows v13 on 2026-02-07, v13-rc1 on 2025-12-09 and v12.5 on 2024-11-13, so the tagged releases exist, but the README does not say which branch each tag corresponds to or how to check out a tag. If you need a known state, verify the tag yourself rather than assuming the clone is on it.

The third limitation is the dependency surface. libconfig 1.7 or newer is required, and if your system has an older version, the README says meson will try to build it from git, which adds cmake and git to the requirements. That is a build-time surprise on distributions that ship older libconfig. Similarly, the optional features are opt-out at configure time, not opt-in: dbus, opengl and regex are enabled unless you pass -Ddbus=false, -Dopengl=false or -Dregex=false. A minimal build is possible, but only if you know to ask for it.

picom compared with running a compositor inside the desktop environment

The realistic alternative is not another standalone compositor but the one already bundled with a desktop environment, such as Mutter under GNOME or KWin under KDE Plasma. Those compositors are not separable from the shell: they handle window management, input, and effects in one process, and they are configured through the desktop's own settings panels rather than a text file.

The difference in approach matters in two ways. First, integration: a desktop compositor knows about its own window manager's state, so effects follow the desktop's conventions automatically. picom has to infer window roles from X properties and rules, which is why the configuration file contains match rules and why libpcre2 is an optional dependency for regex matching. Second, control: picom exposes its effects as configuration keys in picom.sample.conf and its internals as D-Bus control when built with libdbus, which is more granular than a settings panel but also more work to get right.

For a tiling window manager user, the desktop compositor is not an option at all, because there is no desktop shell to provide it. That is the gap picom fills. For a GNOME or KDE user, replacing the built-in compositor with picom is a downgrade in integration for no clear gain.

Maintenance, licensing and the cost of upgrading

The repository is not archived, and the last push was on 2026-09-22. Release cadence is visible in the tags: v12.5 in November 2024, v13-rc1 in December 2025, and v13 in February 2026. That is roughly one release per year, with a release candidate about two months before the final tag. The CHANGELOG.md file at the repository root is the place the project points to for changes, alongside the GitHub releases page.

Upgrade cost is mostly configuration drift. picom is configured through picom.sample.conf, and the README does not document a migration path between versions or a compatibility guarantee for configuration keys. The man pages under man/ are the reference. If you build from the next branch rather than a tag, you are tracking an explicitly bug-prone line, so the upgrade cost is not just re-reading configuration but also absorbing whatever regressions the branch carries.

Licensing is a mixed picture. The README states that picom is free software made available under the MIT and MPL-2.0 licences, and that the individual source files should be consulted for details. The repository root contains LICENSES/, COPYING and LICENSE.spdx, which is where those per-file terms live. The repository metadata labels the licence as NOASSERTION, which means GitHub could not classify it automatically; it does not mean the project is unlicensed. If you redistribute picom or link against it, read the per-file headers rather than relying on the top-level summary, since MIT and MPL-2.0 carry different obligations. This is a description of what the repository states, not legal advice.

Editorial conclusion

picom fits users of bare X11 window managers such as i3, dwm or xfce who want compositing effects without pulling in a full desktop environment, and who are willing to build it with meson or install a distribution package. It is the wrong tool for Wayland sessions, where the compositor is part of the display server, and for anyone who needs a stable release rather than the development branch the repository describes as bug-prone. Before adopting it, check which branch your package tracks, whether libconfig 1.7 or newer is present on your system, and which optional features (dbus, opengl, regex) your build enables, since those flags decide what the binary can do.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. yshui/picom on GitHub