picom builds with meson, but the default branch is the unreleased one
A lightweight compositor for X11 with animation support
At a glance
- What is it?
- picom is a fork of Compton that composites X11 windows with animation support. Building it takes two commands, while adopting it means deciding whether the next branch or a tagged release is what you want to run.
- Who is it for?
- picom fits an X11 user who wants a compositor they can build from source with meson and who is willing to track a development branch. It does not fit someone who needs a documented configuration reference or a stable default branch: the page warns that bugs are to be expected on the branch it defaults to, and sends its change log to the releases page instead.
- Can I use it commercially?
- Check first. The repository uses a licence we do not classify automatically, so read its LICENSE file before any commercial use.
- Is it still maintained?
- Yes. The repository last received commits 19 days ago.
- What is it written in?
- Mainly C, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- yshui/picom4,830 ★ · +26
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| yshui/picom | 4.8k | 4.8k |
26 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
Default branch is next, and the page warns about bugs
The default branch for picom is next, and the front page states plainly that this is a development branch and that bugs are to be expected. A clone with no arguments therefore gives you unreleased code. Tagged releases exist and are named separately: v13 was published on 2026-02-07, v13-rc1 on 2025-12-09, and v12.5 on 2024-11-13, and the README's Change Log section is a link to the releases page. CHANGELOG.md does exist at the top level, so the history is split between a file and a release feed. The last push was on 2026-10-27, months after the v13 tag, which is what you would expect from a branch that keeps moving after a release. The same page asks for feedback through the discussions tab or Discord, and it says that merely compiling and running this branch and reporting what you find counts as a contribution.
meson builds it and the binary lands in build/src
The build is two commands and the install is a third:
meson setup --buildtype=release build
ninja -C build
ninja -C build installThe compiled binary is found in build/src, which is worth remembering because the build directory is created by the setup command with that exact name and the install step is what puts the binary on your PATH. The default install prefix is /usr/local, and the page gives you the way out: `meson configure -Dprefix=<path> build` changes it. Since /usr/local is a system location, the choice of prefix decides whether the compositor lands somewhere shared or inside a directory you own, and nothing else in the instructions prompts you for that decision. The build type is spelled out in the setup command rather than defaulted, so a debug build is a deliberate change to the same line.
Three libraries can be switched off at configure time
The dependency list marks three libraries as optional, and each one has a configure flag that removes it:
libconfig (>= 1.7)
libdbus (optional, disable with the `-Ddbus=false` meson configure flag)
libGL, libEGL, libepoxy (optional, disable with the `-Dopengl=false` meson configure flag)
libpcre2 (optional, disable with the `-Dregex=false` meson configure flag)That is a real choice with a real cost, because the page names the library behind each flag and not the features behind it. Turning off the OpenGL group removes the GL libraries and epoxy from the build, and nothing on the page says which rendering paths disappear with them. The same silence applies to the D-Bus toggle and to dropping libpcre2 for the regex option. If you disable one of these because your distribution lacks the package, you are finding out what the flag costs through trial, not through documentation. The rest of the list is mandatory: libx11, libx11-xcb, xproto and the long run of xcb modules including damage, xfixes, shape, render, randr, composite, image, present and glx, plus pixman, libev and uthash.
libconfig below 1.7 drags cmake and git into the build
libconfig 1.7 or later is the one version constraint in the whole dependency list. When your system does not have it, meson tries to build libconfig from git, and at that point you also need cmake and git installed, which are not in the dependency list itself. The repository ships a subprojects/ directory, which is where that fallback lands. So a distribution with an older libconfig does not fail fast with a clear error, it changes the shape of your build: a network fetch and a nested build join the meson run. Documents are a separate dependency of their own, since building them needs asciidoctor. Beyond that, the page assumes the usual toolchain is already present and names gcc, python, meson and ninja as examples of what it expects you to have.
Package lists stop at Debian and Fedora
Two distributions get a full package list, and they get it as one long line each. On Debian based systems such as Ubuntu:
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-devOn Fedora:
dbus-devel gcc git libconfig-devel libev-devel libX11-devel libX11-xcb libxcb-devel libGL-devel libEGL-devel libepoxy-devel meson pcre2-devel pixman-devel uthash-devel xcb-util-image-devel xcb-util-renderutil-devel xorg-x11-proto-devel xcb-util-develNothing covers Arch, even though the repository carries flake.nix, flake.lock and package.nix at the top level, so on any other distribution you map the dependency names yourself and hope your package manager spells them the same way. The Debian list also shows the meson flags are not applied there: dbus, GL and the regex library are all included.
Libraries outside the default prefix need CPPFLAGS and LDFLAGS
meson does not look for dependencies outside the default locations, so a system that keeps headers and libraries under /usr/local needs to be told. The page gives the general form and then a FreeBSD example:
LDFLAGS="-L/usr/local/lib" CPPFLAGS="-I/usr/local/include" meson setup --buildtype=release build
ninja -C buildThe detail that matters is where those variables go. They are passed to `meson setup`, the step that creates the build directory, and not to `ninja`, so they have to be present the first time you configure. If you set them afterwards and rerun only the compile step, the flags are ignored and the same missing dependency error returns. The instruction to set CPPFLAGS and LDFLAGS applies to headers and libraries installed at non default locations, which is the normal case on FreeBSD and on any system where a second package manager or a manual build has already written into /usr/local.
The tree keeps Compton's desktop file and a sample conf
The top level tells you what you get and what survived the fork from Compton:
picom.sample.conf
man/
dbus-examples/
compton.desktop
picom.desktopBoth desktop files are present, the old Compton one and the picom one, which is a small sign of how the rename was handled. picom.sample.conf is the configuration reference that the build instructions never describe, and man/ and dbus-examples/ are where the interface documentation lives. Below that sit src/, include/, tests/, tools/, data/, media/ and bin/, plus meson.build, meson/ and meson_options.txt for the build definition and the flags used above. Continuous integration is configured through .circleci/ with a coverage service badge at the top of the page, and flake.nix with flake.lock sit alongside the Nix packaging. History.md keeps the original Compton README, so upstream notes are still reachable from this repository.
Two licenses, and the metadata field asserts neither
Licensing is stated in two sentences: picom is free software under the MIT and MPL-2.0 licenses, and you should see the individual source files for details. That last clause is the operative one, because a dual licensed C project can put different terms in different files and the page does not enumerate which is which. The repository carries LICENSES/ with MIT and MPL-2.0 directories, a COPYING file and a LICENSE.spdx file, which is where the per file detail is meant to be resolved. Meanwhile the repository metadata field for the license reads NOASSERTION, so tooling that only looks at that field will not tell you what the code is under. Contributors are listed in a CONTRIBUTORS file, and the collaboration policy is unusually explicit: becoming a collaborator takes significant time, you reply to issue reports and review pull requests, you cannot push to the main branch directly, and everything you write still goes through code review.
Editorial conclusion
picom fits an X11 user who wants a compositor they can build from source with meson and who is willing to track a development branch. It does not fit someone who needs a documented configuration reference or a stable default branch: the page warns that bugs are to be expected on the branch it defaults to, and sends its change log to the releases page instead. Before you run it, read picom.sample.conf, choose between a tagged release such as v13 and the next branch, confirm your libconfig is at least 1.7 so meson does not fall back to building it from git, and pick your own install path with `meson configure -Dprefix=<path> build` if /usr/local is not where you want the binary.
Frequently asked questions
How do I install picom from source?
Configure the build with `meson setup --buildtype=release build`, compile with `ninja -C build`, and install with `ninja -C build install`. The built binary appears in build/src, and the default install prefix is /usr/local, which you change with `meson configure -Dprefix=<path> build`.
How do I install picom on Debian or Ubuntu?
The README gives one package line for Debian based systems such as Ubuntu: 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
How do I install picom on Fedora?
The Fedora package list in the README is: dbus-devel gcc git libconfig-devel libev-devel libX11-devel libX11-xcb libxcb-devel libGL-devel libEGL-devel libepoxy-devel meson pcre2-devel pixman-devel uthash-devel xcb-util-image-devel xcb-util-renderutil-devel xorg-x11-proto-devel xcb-util-devel.
How do I install picom on Arch Linux?
The README has no Arch package list. The repository does carry flake.nix, flake.lock and package.nix at the top level, and the build instructions it does give cover a source build with meson and ninja plus package lists for Debian based systems and Fedora.
How do I use picom once it is installed?
The README does not walk through day to day use. The repository carries picom.sample.conf, a man/ directory and dbus-examples/, and the README sends its change log to the Releases page on the site rather than to a section on this page.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/yshui-picom)Star history chart for your README
[](https://hysenlabs.com/projects/yshui-picom)Was this useful?