# Wayland public preview branch **URL:** \ **Category:** News and Announcements\ **Created:** [September 28, 2026, 10:46am UTC](https://forum.juce.com/t/wayland-public-preview-branch/69600 "2026-09-28T10:46:41Z")\ **Posts on this page:** 7\ **Page:** 1
**Author:** ![t0m](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.juce.com/t0m/32/16413_2.png) [@t0m](https://forum.juce.com/u/t0m)\ **Post date:** [September 28, 2026, 10:46am UTC](https://forum.juce.com/t/wayland-public-preview-branch/69600/1 "2026-09-28T10:46:41Z")
We’re excited to announce that a preview of native Wayland support for JUCE is now available on a new public `wayland` [branch](https://github.com/juce-framework/JUCE/tree/wayland) of the JUCE repository. If you develop standalone applications, audio software, or embedded Linux products, please give this branch a try! ## Native Wayland by Default When a standalone JUCE application starts in a Wayland session (`WAYLAND_DISPLAY` is set), JUCE will attempt to create native Wayland peers. If Wayland is unavailable, JUCE falls back to X11. The Wayland libraries are loaded at runtime, allowing the same application binary to run in native Wayland, X11, and XWayland environments. The Wayland backend adds no build dependencies to `juce_gui_basics`. JUCE talks to the compositor through its own protocol bindings and loads `libwayland-client` at runtime. X11 remains a supported JUCE backend. Plugin editors will continue to use X11/XWayland. Note that this preview compiles both Wayland and X11 backends (the X11 development headers remain build dependencies at this time). ## Desktop and embedded Linux In addition to desktop Linux, embedded Linux has been an important driver for this work. Standalone JUCE applications can now run directly on Weston without requiring an XWayland server merely to display their interface. This is useful for musical instruments, effects processors, control surfaces, kiosks, and other dedicated products built around Yocto or similarly focused Linux images. Touch input arrives directly from the compositor, so touch panels work on systems with no X server at all. Wayland’s OpenGLContext support includes OpenGL ES and has been tested by the JUCE team on embedded hardware. ## What Wayland adds over X11 The Wayland backend includes first-class desktop features such as: - Chinese, Japanese, and Korean (CJK) support for Input Method Editors (IMEs) - Smooth touchpad scrolling - High-resolution mouse wheels with natural scrolling - Compositor-driven repainting - Ability to run on systems without X11 - Fractional scaling (for example 125% or 150%, per-monitor) and HiDPI support. - Hot-plug display support - File chooser integration through XDG Desktop Portal - Some default embedded hardware operating systems require Wayland to access OpenGL or other, similar, hardware accelerated graphics contexts ## Known Limitations Wayland is currently limited to standalone applications. Plugin editors continue to use X11/XWayland. Other things to note: - `WebBrowserComponent` is heavily dependent upon specific X11 machinery and is therefore not available on Wayland. - `toFront()`, `toBehind()`, and always-on-top have no Wayland equivalent. - Wayland is very strict about popup/menu ordering and window placement. Wayland has no global window coordinates. A window cannot read or set its own screen position. The compositor ultimately decides where windows land. Please let us know if you see any issues here! ## Known issues under investigation - Popup placement from hosted audio plugins - Drag and drop icon placement - Generic titlebar icons displayed ## Testing The JUCE team has tested on multiple versions of GNOME (Mutter), KDE Plasma (KWin), Hyprland, and Weston as well as on embedded hardware. Feedback from different distributions, compositors, and display configurations is very much appreciated! Please reply to this thread with any problems you encounter. Reports are most helpful when they include: - Linux distribution and version - Desktop environment and Wayland compositor - Whether the application used software rendering, OpenGL, or OpenGL ES - Whether the problem also occurs under X11/XWayland To compare a problem against the X11 backend on the same machine, start your app with `WAYLAND_DISPLAY` unset: ```auto env -u WAYLAND_DISPLAY ./MyApp ``` In the rare event that your app closes suddenly, it’s likely the compositor rejecting a request and closing the connection. Run your app from a terminal with `WAYLAND_DEBUG=1` and with stderr redirected to a file: ```auto WAYLAND_DEBUG=1 ./MyApp 2> wayland.log ``` Please send us the last 50 lines of that log. ## Usage and Development Given the diversity of Linux-based systems we anticipate that this public preview branch will uncover a number of new issues for us to fix, on top of the limitations and known issues already listed in this thread. However, for many embedded systems without particularly complex interactive UIs, this preview branch may already be stable enough to use immediately. ---
**Author:** ![t0m](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.juce.com/t0m/32/16413_2.png) [@t0m](https://forum.juce.com/u/t0m)\ **Post date:** [September 28, 2026, 10:47am UTC](https://forum.juce.com/t/wayland-public-preview-branch/69600/2 "2026-09-28T10:47:15Z")
---
**Author:** ![KottVV](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.juce.com/kottvv/32/14169_2.png) [@KottVV](https://forum.juce.com/u/KottVV)\ **Post date:** [September 30, 2026, 4:03am UTC](https://forum.juce.com/t/wayland-public-preview-branch/69600/3 "2026-09-30T04:03:49Z")
This is really great. I tested Wayland APH and didn’t get any issues so far. Is it correct, that plugins are just waiting for the settled window-embed specification for Wayland? ---
**Author:** ![t0m](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.juce.com/t0m/32/16413_2.png) [@t0m](https://forum.juce.com/u/t0m)\ **Post date:** [September 30, 2026, 11:09am UTC](https://forum.juce.com/t/wayland-public-preview-branch/69600/5 "2026-09-30T11:09:54Z")
We’ve not yet decided how best to provide native Wayland plug-ins and plug-in hosting. There is some prior precedent in the VST3 SDK and from PreSonus, but there are caveats to that approach. At the moment we’re concentrating on the known issues with the branch, then looking at WebBrowserComponent. ---
**Author:** ![drmr-2](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.juce.com/drmr-2/32/19860_2.png) [@drmr-2](https://forum.juce.com/u/drmr-2)\ **Post date:** [September 30, 2026, 11:11am UTC](https://forum.juce.com/t/wayland-public-preview-branch/69600/6 "2026-09-30T11:11:24Z")
One issue with plugins is that only VST3SDK has a preview of a potential implementation (taken from Fender Studio One). So there need to be equal implementations for the other plugin formats. Wayland doesn’t offer proper mechanisms to do this for the plugin use-case, so all the proposals are kind of “hacks” on top of what Wayland is able to do. There are several discussions on github (LV2 and CLAP repositories) that go into depth on this. ---
**Author:** ![t0m](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.juce.com/t0m/32/16413_2.png) [@t0m](https://forum.juce.com/u/t0m)\ **Post date:** [October 1, 2026, 1:04pm UTC](https://forum.juce.com/t/wayland-public-preview-branch/69600/7 "2026-10-01T13:04:00Z")
I’ve just pushed some changes that make it a bit easier to get started on systems that only support OpenGL ES, like the i.MX family of boards. You can now compile the DemoRunner with just the following changes to the DemoRunner’s CMakeLists.txt: ```diff @@ juce_add_gui_app(DemoRunner NEEDS_CURL TRUE - NEEDS_WEB_BROWSER TRUE + NEEDS_WEB_BROWSER FALSE + NEEDS_OPENGL_ES TRUE @@ target_compile_definitions(DemoRunner PRIVATE - JUCE_WEB_BROWSER=1 + JUCE_WEB_BROWSER=0 + JUCE_USE_XINERAMA=0 + JUCE_USE_XCURSOR=0 + JUCE_ALSA=0 ``` You may need to disable additional `JUCE_USE_X*` depending on your setup. ---
**Author:** ![mgrand](https://sea2.discourse-cdn.com/flex026/user_avatar/forum.juce.com/mgrand/32/14447_2.png) [@mgrand](https://forum.juce.com/u/mgrand)\ **Post date:** [October 20, 2026, 7:13am UTC](https://forum.juce.com/t/wayland-public-preview-branch/69600/8 "2026-10-20T07:13:53Z")
That’s great! I’ve been encountering only one issue with popup menus. They appear much smaller on Wayland than with X11 on my machine. I’m using Ubuntu 26.04.1 (Gnome) on a retina display, with the display scale set to 133%. Debugging the MenuWindow with and without `WAYLAND_DISPLAY` reported this: | | Wayland | X11 | | --- | --- | --- | | `baseScale` | 1.0 | 1.0 | | `targetScale` | 1.33333 | 2.0 | | `selfScale` | 2.0 | 2.0 | | `scaleFactor` | 0.66667 | 1.0 | Hope this helps