Smithay: building Wayland compositors in Rust without writing a compositor library

What Smithay actually provides, and who it is for

The README is explicit that Smithay is not a full-blown compositor. It is a library of objects and interfaces that "pretty much any compositor will need", written generically so you can assemble them yourself. The project description in Cargo.toml says the same thing in one line: a library for writing Wayland compositors.

That framing decides the audience. If you are building a compositor and you want to spend your time on window management policy, input semantics, or a shell, Smithay is aimed at you. If you want to run a desktop, Smithay is the wrong layer entirely. The repository does ship sample compositors, anvil and smallvil, but the README points at anvil as a sample rather than a product, and sends new users to GETTING_STARTED.md before anything else.

The protocol surface is broad but not exhaustive. Smithay supports the core Wayland protocols, the official protocol extensions, and some external extensions, specifically those made by and for wlroots and KDE. The word "some" is doing real work there. If your compositor depends on an extension outside those families, you should check the source before assuming it is present.

Modularity as an architectural choice, not a slogan

The README lists modularity as a goal with a specific meaning: Smithay is not a framework and does not impose constraints, and you are never required to use components you do not need. That is a different posture from a compositor toolkit that hands you a main loop and a scene graph and expects you to fill in the blanks.

The dependency list in Cargo.toml shows how far this goes. Many of the heavier pieces are optional: ash, drm, drm-ffi, drm-sys, gbm, glow, input, libseat, libloading, scopeguard, siphasher, and tempfile all carry the optional flag. The base crate pulls in calloop for the event loop, tracing for instrumentation, rustix for system calls, and a handful of small utilities. A compositor that runs nested inside another session does not need to compile the DRM or libinput paths at all.

The cost of that choice is that there is no single blessed way to wire things together. You get primitives and you own the composition. The README calls this high-level because you should not have to worry about low-level details, while noting the library will not stop you from going lower. In practice, the amount of glue you write is proportional to how much of the stack you replace.

Installing Smithay and running the minimal example

Smithay is published on crates.io, and the repository targets Rust edition 2024 with a minimum supported Rust version of 1.87. Adding it to an existing crate is a normal Cargo dependency, and the Cargo.toml dependency entry is named smithay.

smithay = "0.7.0"

The README states that the best place to start is the getting started guide in the repository, so the first real step after adding the dependency is to read GETTING_STARTED.md rather than to guess at an entry point. The repository also contains a set of example files, including examples/minimal.rs, examples/compositor.rs, examples/seat.rs, examples/buffer_test.rs, and examples/vulkan.rs. Cargo resolves the local crate rather than a published version when you build from a clone of the workspace. The README does not describe the visual output of each example, so treat the source file as the specification.

System dependencies matter before any of this compiles. The README lists libwayland, libxkbcommon, libudev, libinput, libgbm, libseat, xwayland, libEGL, libpixman, and libdisplay-info, and notes that the exact list depends on which features you enable. If you only build the nested path, you can likely drop the DRM and input libraries, but that is a judgement about feature flags rather than something the README spells out per feature.

Where Smithay stops being the right tool

The clearest limitation is the one the project states about itself: it is not a compositor. A new user expecting to install Smithay and get a usable session will not find one. The samples exist to demonstrate the library, and the README describes anvil as a sample compositor with its own README, not as something to ship to end users.

There is a second boundary around protocol coverage. Smithay supports core protocols, official extensions, and some external extensions from wlroots and KDE. Anything outside that set is not promised. A compositor that needs an extension from another vendor has to implement the interface itself or wait.

The dependency surface is the third constraint. Building a full compositor against Smithay means linking against a long list of system libraries, several of which are optional but all of which are real work to provision. On a distribution that ships older versions of libinput or libgbm, you may spend more time on packaging than on compositor logic. The README does not document rollback or compatibility matrices for those libraries, so version pinning is on you.

Finally, the maintenance picture: the last push to the repository was on 2026-09-22, which is recent, and the most recent release is v0.7.0 from 2025-06-24. The release cadence visible in the notes is roughly every two months across v0.5.0, v0.6.0, and v0.7.0, which matters if you depend on pre-1.0 APIs that can shift between versions.

Smithay against wlroots: same problem, different language boundary

The comparison people actually search for is Smithay versus wlroots, and the difference is not feature parity so much as where the abstraction sits. wlroots is a C library that compositors link against, and it is the base for a large family of existing compositors. Smithay occupies the same conceptual slot in Rust.

The practical consequence is the extension story. Smithay explicitly includes some external extensions made by and for wlroots, which means the protocol work done in that ecosystem is partly reusable here. But the language boundary is absolute: a wlroots compositor is C, and a Smithay compositor is Rust. You cannot mix the two in one process without a foreign function interface layer, and the README describes no such bridge.

The list of compositors built on Smithay in the README gives a sense of the range: Cosmic, Niri, Pinnacle, Strata, MagmaWM, Catacomb, emskin, Sudbury, wprs, Local Desktop, Otto, DriftWM, and Denial. Those projects differ enormously in scope, from a scrollable tiling compositor to an Android app running GUI Linux. That spread is the strongest evidence that the library's modularity claim holds up in practice, because a narrow toolkit could not serve all of them.

Licence, contribution terms, and the cost of upgrading

Smithay is MIT licensed, stated in both the README badge and the Cargo.toml license field. MIT is permissive and imposes no copyleft obligation on your compositor, which is the usual reason projects in this space pick it. This is a description of the licence text, not legal advice; if your organisation has specific requirements, read LICENSE.txt.

Contributing has a condition attached. The README states that to submit code you must agree to the Developer Certificate of Origin, documented in DCO.md, and that a separate AI.md policy applies if you use generative AI. Both files sit at the top level of the repository, so they are easy to find before you open a pull request.

Upgrade cost is the part worth budgeting for. The crate is pre-1.0 at v0.7.0, and the release notes show three releases in 2025 alone, in February, April, and June. Pre-1.0 Rust crates conventionally allow breaking changes in minor versions, so a bump from v0.6.0 to v0.7.0 is not guaranteed to be a drop-in. CHANGELOG.md is the file to read before each bump. The MSRV of 1.87 is also a floor: if your build environment pins an older toolchain, you upgrade that first.

Editorial conclusion

Adopt Smithay if you are writing a compositor in Rust and want protocol handling, input, and rendering primitives rather than a full framework; the README states it is not a framework and does not impose constraints, so you keep control of policy. Do not adopt it if you want a working desktop out of the box, since the repository ships samples such as anvil and smallvil rather than a product. Before committing, check the GETTING_STARTED.md guide, confirm the system dependency list matches your target, and read AI.md if you use generative AI in contributions, because the project states a policy for that.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. Smithay/smithay on GitHub