Louvre: a C++ library that hands you a Wayland compositor and lets you override it piece by piece

Default implementations you replace one at a time

Louvre is a C++ library for building Wayland compositors. The architectural decision that defines it is the use of the Factory Method pattern to provide default implementations for all major functionality and protocols, which you can gradually override.

That design has a direct consequence for how a project starts. You get results from day one, which the project describes as potentially easing the learning curve, while you still keep full control to create a unique, custom compositor. In practice this means the library hands you a working set of protocol implementations and a set of extension points, and the compositor you ship is the sum of the pieces you replace.

For somebody learning the Wayland protocol set this is a significant shortcut. The protocol list alone is long, and each one has its own negotiation dance. Starting from a library that already speaks them means the first thing you write is policy rather than plumbing.

The project is published as source with the build files in the tree, including meson.build, meson_options.txt, pkg/ and scripts/ directories, a src/ directory, doxygen/ for the documentation generation, and a VERSION file alongside a CHANGES file. It is released under LGPLv2.1, and the project page carries an API documentation link, a tutorial, a set of examples, a downloads page, an environment page, a contact page, a gallery of projects using Louvre and a video demo. The documentation is published on the web, and the project states that the web documentation corresponds to the latest release.

The feature list marks its own unfinished work

The features section is short, and three entries carry a work in progress marker. Direct Scanout is listed as WIP, Screencasting is listed as WIP, and in the graphics APIs section Vulkan is listed as WIP. That candour is useful, because those three are exactly the items a compositor author is most likely to need and least likely to be able to build from the library alone.

The finished parts cover the ground that a working compositor needs. Explicit synchronization is there, along with VSync control and gamma correction. Fractional scaling comes with optional antialias. Hardware coverage includes hybrid GPU support, multi-session support, double and triple buffering, and a persistent clipboard.

The XWayland entry is the one to read twice. Louvre offers rootful XWayland, and rootless mode is not supported. The project is direct about the workaround, and names three projects that can provide a rootless experience: Wayland Transpositor (wprs), Wayland Proxy Virtwl, and Xwayland Satellite. That is a concrete architectural boundary rather than a missing feature, and it is the single constraint most likely to shape your project plan.

Fractional scaling and hybrid GPU support are the two that change how a compositor feels in daily use, and both are listed as available.

The protocol surface is where the compositing work already happened

The protocols list is the clearest evidence of the work the library has already absorbed. The XDG family is fully present, with XDG Shell, XDG Output, XDG Decoration and XDG Activation.

Shell and session work is covered by Wlr Layer Shell, Wlr Output Management, Session Lock, and the wlr protocols for Foreign Toplevel Management and Gamma Control. Session Lock in particular is the piece that makes a secure screen lock possible, and implementing it correctly is not trivial.

The graphics and input side runs through Linux DMA-Buf, Mesa Wayland DRM, DRM Lease, DRM synchronization object, Fractional Scale, Cursor Shape, Pointer Constraints, Pointer Gestures, Relative Pointer, Presentation Time, Tearing Control, Viewporter, Single Pixel Buffer, Idle Notify, Idle Inhibit, Image Capture Source, Foreign Toplevel List and Content Type Hint.

There are also three Louvre specific protocols, marked with the Lvr prefix, which the project adds on top of the standard set: Lvr Background Blur, Lvr Invisible Region and Lvr SVG Path. These exist because the underlying Wayland protocols have no equivalent, and a compositor that wants a blurred background or an invisible region has to define the behaviour itself.

If your plan involves a protocol that is not on this list, it is not supported by the library today, and you would be writing it against the wire format yourself.

Backends and graphics APIs decide what you can test

Three backends are listed: DRM/KMS, Wayland and Offscreen. The DRM/KMS backend is the real display path, talking to the kernel mode setting interface. The Wayland backend is what lets a compositor host other Wayland clients inside itself, which is how nested and embedded sessions are built. The Offscreen backend is the interesting one for development, because it gives you a rendering target that is not a physical display, which is how you develop and test a compositor on a machine without the target hardware attached.

On the rendering side there are three graphics APIs: OpenGL, Raster and Vulkan, with Vulkan marked as work in progress. The practical reading is that a Vulkan based compositor is not something the library carries you through today, while OpenGL and Raster are the paths with support behind them.

Together, the backend and API lists describe the two axes you choose early. The backend decides where output goes and what you can nest into; the graphics API decides what you can render and how you present frames. Both are overridable, since the whole library is built on overridable defaults, but a project that intends to use Vulkan will be writing that path itself.

The project publishes an environment page alongside the documentation, which suggests the build and runtime dependencies are documented there rather than in the README.

Getting the source and knowing which version you are on

The documentation gives one clear instruction about versions: check the releases section for stable versions, and the web documentation corresponds to the latest release. Everything else is left to the linked pages, with a downloads page, a tutorial, examples, and an API reference hosted on the project site.

What the README does not give is a build recipe. There is no command sequence in the documentation text to copy, so the honest instruction is to follow the environment page for the build dependencies, then the downloads page for the packages, and the tutorial for the first project. Inventing a configure and compile command that the project never wrote down would be worse than saying the build steps live on the environment page.

The repository itself is a good place to look for the structure of a build. There is a meson.build at the root with a meson_options.txt beside it, a pkg/ directory that conventionally holds the package metadata files, a scripts/ directory for helper scripts, and a src/ directory for the library sources. The VERSION file and the CHANGES file are the fastest way to see where a checkout sits relative to a published release, and doxygen/ holds the documentation sources that produce the API pages.

For a first evaluation, the example projects linked from the documentation are the lowest friction starting point, since they show a compositor assembled from the library rather than an empty skeleton.

LGPLv2.1 and a release trail that runs behind the main branch

The library is released under the LGPLv2.1, and the licence file is in the repository. What that means for a compositor that links Louvre is a question with legal dimensions rather than a technical one, so the practical advice is short: read the licence text, and be aware that the obligations attach to how you distribute the combination rather than to how you use it internally.

The version picture needs a second look. The badge on the project page states the current Louvre version as 3.0.0, while the tagged releases in the history are v2.18.1-1 from 2025-05-19, v2.18.0-1 from 2025-05-11 and v2.17.0-1 from 2025-05-02. The repository is not archived, and the last push was on 2026-10-15.

So the main branch is well ahead of the last published tag, and the badge describes a version that has not appeared as a release in that list. If you want the state of the project described in the documentation, the main branch is where it is, and it carries the usual risk of tracking a moving branch. If you want a tagged point of reference, v2.18.1-1 is the newest one, and it is more than a year older than the last commit.

The CHANGES file in the tree is where the differences between those two points are described, and it is worth reading before choosing which one you base a project on.

Louvre against writing the protocols yourself

The realistic alternative is to implement the Wayland protocol set yourself, talking to clients over the wire format directly. The difference in approach is the whole point of the library. Writing them yourself means you own every version negotiation, every event ordering rule and every edge case in the specification, and you can shape the compositor exactly as you want. You also inherit the risk, since a subtle protocol bug shows up as a client that misbehaves in ways that are hard to attribute.

Using Louvre means accepting a set of defaults that somebody else designed, in exchange for not writing them. The Factory Method structure keeps that trade honest, because each default sits behind an override point, so the parts you care about can be replaced without discarding the rest. The cost is that the compositor you ship is partly a product of the library's opinions, and a behaviour that is wrong for your design is a bug in someone else's code rather than a missing line in yours.

For the XWayland case there is a third option that Louvre itself points at. Rather than forcing rootless XWayland into the library, projects such as wprs, virtwl and Xwayland Satellite provide the rootless experience alongside it, which means you can compose the pieces instead of waiting for the library to change.

The honest summary is that Louvre removes the protocol work and keeps the policy work. If your compositor is mostly policy, that is a good deal. If it is mostly protocol experimentation, you will spend your time fighting the defaults instead of exploring.

Editorial conclusion

Adopt Louvre if you are writing a Wayland compositor in C++ and want XDG Shell, Layer Shell, Output Management, Session Lock, pointer constraints and the DRM path already implemented, with the freedom to replace one factory at a time. Do not adopt it if you need rootless XWayland, a Vulkan renderer, or a complete desktop shell, since rootless mode is not supported, Vulkan is work in progress, and the library is a foundation rather than a product. Verify first which release you take, because the version badge on the project page reads 3.0.0 while the latest tagged release is v2.18.1-1 from 2025-05-19, and check the LGPLv2.1 terms against your linking model before you commit.

Frequently asked questions

Official sources

1. CuarzoSoftware/Louvre on GitHub
2. Issues
3. License: LGPL-2.1
4. README
5. Releases