Qt embedded Raspberry Pi development with EGLFS, Wayland, and LinuxFB
Why Qt embedded Raspberry Pi projects need a platform decision first
Qt embedded Raspberry Pi development is not only a matter of installing Qt and launching a demo. The first engineering decision is how the application will control the screen, input devices, graphics stack, and update path. A kiosk, HMI, medical accessory, industrial dashboard, or smart hardware prototype may use the same Raspberry Pi board, but that does not mean they should use the same Qt platform backend. For many single-application devices, EGLFS remains a strong option because it lets one Qt application run directly on the display without a conventional desktop. For multi-window or multi-process systems, Wayland is usually the more flexible architecture. LinuxFB is still useful for simple software-rendered interfaces, but its limits need to be understood before the UI grows.
The practical conclusion is straightforward: choose the display architecture before choosing the build method. A project that starts on the wrong backend can look acceptable during prototyping, then break down when touch input, GPU acceleration, screen rotation, remote maintenance, or multiple processes are added. This article focuses on the engineering choices behind Qt on Raspberry Pi for embedded devices, with attention to the current Qt 6 embedded Linux model and Raspberry Pi OS display direction.
For more embedded board and platform coverage, see the embedded platforms section.
Qt on Raspberry Pi is different from desktop Qt
On a desktop Linux machine, Qt applications commonly run inside a desktop session with a display server and a window manager. On an embedded Raspberry Pi product, that stack may be unnecessary, and in some cases it adds services and behavior the product does not need. A single full-screen interface may need fast boot, controlled input, predictable rendering, and a small runtime footprint. Qt for Embedded Linux addresses this by providing platform plugins that change how the application connects to display and input systems.
Qt documentation describes several embedded Linux platform plugins, including EGLFS, LinuxFB, Wayland, XCB, and the more specialized VkKhrDisplay path. These are not interchangeable names for the same layer. They make different assumptions about graphics acceleration, window management, and system architecture. EGLFS uses EGL and OpenGL ES without a normal windowing system and is intended for devices where one Qt application controls the display. Wayland uses a compositor and is better suited when multiple client processes or a richer shell model are required. LinuxFB writes through the Linux framebuffer path and supports software-rendered content, which makes it simpler but usually less capable for modern Qt Quick interfaces.
Raspberry Pi adds another layer to the decision. The board family has moved through several graphics approaches over time, and modern 64-bit Raspberry Pi systems commonly rely on the kernel modesetting and DRM stack rather than older vendor-specific display paths. Qt 6 documentation specifically notes that Raspberry Pi 4-class systems commonly use EGLFS with the KMS/DRM-oriented eglfs_kms backend, which uses DRM and GBM for display and buffer management. In plain terms, a production-oriented embedded Qt deployment should treat the graphics stack as part of the platform, not as a detail to fix at the end.
Choosing between EGLFS, Wayland, and LinuxFB
The central architectural question is whether the product is a single-application device or a small graphical system with multiple processes. Many Qt embedded Raspberry Pi projects start with a full desktop because it is convenient during development, then struggle when the team tries to remove it later. The opposite mistake also happens: a team chooses a bare full-screen backend, then discovers that the product needs a compositor, screen sharing, overlays, or separate UI processes.
| Backend | Best fit | Main advantages | Main limits |
|---|---|---|---|
| EGLFS | Single full-screen Qt application | Direct display control, GPU acceleration when the graphics stack is correct, simpler runtime than a desktop session | Typically one top-level full-screen window per screen; not designed for a normal multi-window desktop model |
| Wayland | Multi-process embedded UI, custom shell, systems with separate graphical clients | Modern compositor-based architecture, better fit for multiple windows or clients, aligned with the broader Linux graphics direction | Requires a compositor and more system integration work than a single EGLFS app |
| LinuxFB | Simple QWidget-style or raster interfaces with no GPU requirement | Useful for basic software-rendered interfaces and minimal systems | No OpenGL acceleration path; Qt Quick needs the software scene graph and performance may be limited |
| XCB on X11 | Development, legacy desktop-style environments, or compatibility cases | Familiar desktop behavior and tooling | Usually not the preferred embedded production path, especially where a controlled full-screen appliance UI is required |
For a dedicated HMI or kiosk, EGLFS is often the first option to evaluate. It keeps the runtime focused and avoids a complete desktop environment. However, it depends on the underlying graphics drivers, kernel configuration, EGL libraries, and Qt build configuration matching correctly. If accelerated graphics are not reported as available during configuration, a successful Qt compile does not prove that the final application will render correctly.
For a product with multiple UI components, Wayland deserves early consideration. Raspberry Pi OS documentation states that from Bookworm onward, Raspberry Pi OS uses Wayland with labwc by default. It also warns that switching back to X11 is not recommended because X11 is not the active development direction for that platform. This does not mean every embedded product should run the full Raspberry Pi OS desktop. It does mean new long-lived designs should not depend on X11 unless there is a specific compatibility reason.
LinuxFB is best treated as a fallback or a deliberate low-complexity choice. It can be appropriate for simple control panels, diagnostic screens, or systems that do not need animated Qt Quick graphics. It should not be selected only because it appears easier during early testing. If the interface later becomes a modern QML application, the lack of GPU acceleration can become a major constraint.
Build strategy matters as much as the backend
There are three common ways to build or deploy Qt on Raspberry Pi: use distribution packages, cross-compile Qt, or adopt an embedded image workflow such as Boot to Qt or a Yocto-based build. Each route has a different risk profile.
Distribution packages are the fastest path for learning and prototypes. They allow developers to validate application logic, GPIO communication, networking, and basic UI behavior without first building a full SDK. The trade-off is control. Package versions may not match the Qt version used on the development workstation, optional modules may be missing, and the build may not be tuned for the graphics path required by the product.
Cross-compiling gives more control and is often the better direction for a maintained device. Qt documentation for configuring embedded Linux devices emphasizes that Qt is only one part of the software stack. The kernel, user-space graphics libraries, EGL implementation, input libraries, and target filesystem must be consistent. On Raspberry Pi, developers should verify that the configured Qt build reports the expected OpenGL ES, EGL, DRM, GBM, and platform plugin support before treating the build as production-ready.
Boot to Qt and Yocto-style workflows require more setup, but they are attractive when the device needs repeatable images, controlled updates, and a smaller runtime. This approach is less convenient for a quick prototype, but it can reduce surprises when moving from lab units to field devices. A reproducible image also makes compliance, security patching, and factory provisioning easier to manage.
A practical deployment flow for a Raspberry Pi Qt device
A reliable workflow starts with a minimal technical target. Define the Raspberry Pi model, operating system base, display resolution, touch controller, input devices, required Qt modules, graphics backend, and boot requirements before the first production image is built. Otherwise, the team may validate on one graphics path and unknowingly deploy on another.
- Validate the base OS and graphics stack. Confirm that the Raspberry Pi image boots consistently, detects the display, exposes the expected DRM devices, and supports the required EGL or framebuffer path.
- Choose the Qt platform plugin deliberately. Use EGLFS for a controlled single-application display, Wayland for compositor-based multi-client systems, and LinuxFB only when software rendering is acceptable.
- Build or install Qt with matching modules. Qt Quick, Qt Multimedia, Qt SerialBus, Qt WebEngine, and other modules may have different dependency and performance implications. Do not assume they are all present in a minimal runtime.
- Test the application without the development desktop. A Qt app that works inside a desktop session may behave differently when launched directly at boot through a service.
- Measure boot, memory, rendering, and input latency. Raspberry Pi boards are capable, but embedded products need repeatable behavior under load, not just a successful demo.
- Lock the update model. Decide whether updates replace only the application, selected packages, containers, or the full system image.
Environment variables can help during validation. Qt supports variables such as QT_QPA_PLATFORM to choose a platform plugin, and EGLFS has additional variables for integration and display behavior. These should be treated as configuration tools, not random fixes. If a product needs a long list of environment workarounds to start reliably, the underlying platform build should be reviewed. See also: device architecture.
Common pitfalls in Qt embedded Raspberry Pi projects
Assuming a successful build means graphics acceleration works
Qt can compile even when the target graphics stack is incomplete. For EGLFS on Raspberry Pi, the important question is whether the expected EGLFS and KMS/DRM-related support is actually enabled and functional. A build log that reports missing EGL, OpenGL ES, GBM, or the intended EGLFS backend should be treated as a stop sign, not a minor warning.
Developing on a desktop session and deploying headless
Running a Qt application inside a full Raspberry Pi desktop is useful for debugging, but it may hide production issues. Fonts, input permissions, display ownership, GPU access, environment variables, and service startup order can all differ when the application is launched directly at boot. Production tests should match the production launch path.
Choosing LinuxFB for an interface that will become animated
LinuxFB can be acceptable for simple raster UIs. It is not a shortcut to a high-performance Qt Quick system. Qt documentation notes that Qt Quick with LinuxFB requires software rendering. That can be enough for static screens, but it is a weak foundation for fluid animation, transitions, or heavy visual effects.
Ignoring the Wayland transition
Raspberry Pi OS moving toward Wayland changes the assumptions around desktop-style applications. For embedded teams, this is not just a cosmetic change. It affects remote display behavior, compositor choices, legacy X11 assumptions, and how multiple graphical processes are organized. New projects should evaluate Wayland early if they need more than a single full-screen Qt process.
Treating Raspberry Pi as both prototype and final product without review
Raspberry Pi is excellent for prototyping and can be used in many real deployments, but an embedded product still needs review for supply chain, thermal design, storage endurance, electrical environment, enclosure airflow, watchdog behavior, and update recovery. These are product engineering issues rather than Qt issues, but they directly affect whether the Qt application survives outside the lab.
When Raspberry Pi is a strong fit for embedded Qt
Raspberry Pi is a strong fit when the project needs a widely understood Arm Linux platform, strong community knowledge, HDMI display support, networking, camera or USB integration, and enough CPU and GPU capability for a modern interface. It is especially useful for industrial prototypes, internal tools, proof-of-concept HMIs, educational systems, lab instruments, and small-volume products where development speed matters.
It is less ideal when the design needs guaranteed long-term industrial availability, strict real-time behavior, very low power consumption, extended temperature ratings, or deeply customized hardware interfaces. In those cases, the same Qt application architecture may still be useful, but the final board may move to an industrial Raspberry Pi variant, a compute module carrier, or another embedded Linux platform. The key is to keep the Qt application portable by avoiding unnecessary dependence on desktop-only assumptions or board-specific shortcuts.
The best Qt embedded Raspberry Pi architecture is not necessarily the one with the fewest setup steps. It is the one that makes constraints visible early. If the device is a single full-screen appliance, start by proving EGLFS on the exact board and image. If the device needs multiple graphical clients, design around Wayland and a compositor. If the UI is simple and software-rendered, LinuxFB may be enough, but document that limitation before the interface grows.
Frequently asked questions
Can Qt run on Raspberry Pi without a desktop environment?
Yes. Qt can run on embedded Linux without a conventional desktop by using platform plugins such as EGLFS or LinuxFB. EGLFS is the more relevant option for GPU-accelerated full-screen applications, while LinuxFB is mainly for software-rendered interfaces.
Is Wayland required for Qt on Raspberry Pi?
No. Wayland is not required for every Qt Raspberry Pi device. It is most useful when the system needs a compositor, multiple graphical clients, or a modern windowing architecture. A single full-screen embedded application may still be better served by EGLFS.
Should a Qt Quick application use LinuxFB?
Usually not for performance-oriented interfaces. Qt Quick can run with software rendering in some LinuxFB configurations, but that choice limits graphics performance. For animated QML interfaces, an EGL and OpenGL ES path is normally a better starting point.
Can the same Qt application move from Raspberry Pi to another embedded board?
Often yes, if the application is designed cleanly. The UI and business logic can remain portable, while board-specific details such as display backend, input mapping, GPIO access, camera stack, and update system should be isolated behind configuration or platform layers.
What is the safest first step for a production-oriented project?
Start with a platform proof rather than a UI demo. Confirm the target Raspberry Pi model, OS image, graphics backend, Qt version, required modules, touch input, boot method, and update approach. Once those are stable, application development becomes much less risky.
