KiCon 2025 in North America is coming in May!
Get your tickets now to join the KiCad community for 3 days of classes, presentations, and collaboration.

KiCad and Wayland Support

Written by The KiCad Development Team
Published

The KiCad development team frequently receives questions about our support for Wayland. Given that Fedora and Ubuntu are both planning to drop X11 support from their main desktop environments in the near future, we want to provide clear, transparent guidance to our users about the current state of Wayland support in KiCad.

Current Status Is Functional but Degraded

KiCad does run on Wayland systems, but with significant limitations and known issues that substantially degrade the user experience. While you can design PCBs using KiCad on Wayland, you will encounter numerous problems that we cannot fix at the application level.

The following problems are known issues in Wayland protocols or their implementation in desktop compositors, window managers or other layers in the display stack that are beyond our ability to resolve:

Window Management Issues

  • Window placement and restoration: Wayland does not currently allow controlling window position. This means that when you open KiCad, it can not remember where you last placed your windows.

  • Docked panel positioning: Docked panels and toolbars cannot be properly managed or restored

  • Multi-window coordination: Problems with managing multiple KiCad windows simultaneously

  • Window dragging limitations: Dragging tabs and panels between areas is broken or unreliable

Input and Interaction Problems

  • Cursor/pointer warping: Essential for many CAD operations, it is conditionally available in some Wayland implementations, depending on support for optional protocol extensions

  • Focus management: Unpredictable window focus behavior that can interrupt workflows

  • Input device handling: Various issues with specialized input devices and hotkeys

Performance and Stability Issues

  • High CPU/GPU usage: Resource consumption spikes that don’t occur under X11

  • Graphical glitches: Rendering artifacts and display corruption

  • Application freezes and crashes: Instability issues specific to the Wayland environment

  • Clipboard functionality: Unreliable copy/paste operations between applications

Dialog and UI Limitations

  • Modal dialog behavior: Issues with dialog positioning, focus, and interaction

  • External tool integration: Problems launching and managing external applications

Why These Issues Persist

These problems exist because Wayland’s design omits basic functionality that desktop applications for X11, Windows and macOS have relied on for decades—things like being able to position windows or warp the mouse cursor. This functionality was omitted by design, not oversight.

The fragmentation doesn’t help either. GNOME interprets protocols one way, KDE another way, and smaller compositors yet another way. As application developers, we can’t depend on a consistent implementation of various Wayland protocols and experimental extensions. Linux is already a small section of the KiCad userbase. Further fragmentation by window manager creates an unsustainable support burden. Most frustrating is that we can’t fix these problems ourselves. The issues live in Wayland protocols, window managers, and compositors. These are not things that we, as application developers, can code around or patch.

We are not the only application facing these challenges and we hope that the Wayland ecosystem will mature and develop a more balanced, consistent approach that allows applications to function effectively. But we are not there yet.

Our Approach and Policy

The KiCad team has made the strategic decision to:

  • Avoid window manager-specific workarounds that would require maintaining separate code paths for different desktop environments

  • Continue building and testing Wayland compatibility where possible, but without dedicating primary development resources to it

  • Focus our limited development time on features and improvements that benefit all users

  • Maintain clear documentation about Wayland limitations to set appropriate user expectations

Bug Report Policy for Wayland Users

We do not investigate or support bug reports related to Wayland-specific issues. This includes problems with:

  • Window positioning, sizing, or focus

  • Application freezes or crashes that don’t occur on X11

  • High CPU/GPU usage unique to Wayland

  • Input device problems specific to Wayland

  • Graphical glitches or rendering issues

  • Clipboard functionality problems

  • Any other issues that cannot be reproduced on X11 systems

Bug reports about KiCad’s internal functionality that don’t involve window management are still welcome and will be investigated normally.

Recommendations for Users

For Professional Use

If you use KiCad professionally or require a reliable, full-featured experience, we strongly recommend:

  1. Use X11-based desktop environments such as:

    • XFCE with X11

    • KDE Plasma with X11

    • MATE

    • Traditional desktop environments that maintain X11 support

  2. Install X11-compatible display managers like LightDM or KDM instead of GDM if your distribution defaults to Wayland-only

  3. Choose distributions that maintain X11 support - some distributions are moving to Wayland-only configurations that may not meet your needs

For Casual Use

If you’re willing to accept limitations and occasional frustrations, KiCad will run on Wayland. However, be prepared for:

  • Inability to restore your preferred window layouts

  • Occasional crashes or freezes

  • Reduced productivity due to interface limitations

  • Need to work around various UI quirks

Looking Forward

We recognize that the Linux desktop ecosystem is evolving, and we’re not trying to stop that evolution. However, we believe that user productivity comes first - our users need to design circuit boards, not wrestle with experimental desktop technologies. Stability and reliability are paramount for professional work, and our limited development resources should focus on core functionality rather than working around protocol limitations.

We continue to monitor Wayland development and welcome fixes from upstream projects. We’ve engaged with desktop environment developers at conferences like FOSDEM and provided detailed feedback about our requirements. Some progress has been made (pointer warping protocols are finally being developed), but many fundamental issues remain unresolved.

Contributing to Solutions

If you’re a developer interested in improving Wayland support for KiCad there are several ways you can help:

  1. Contribute to upstream projects: Help fix issues in Wayland protocols, window managers, or wxWidgets

  2. Sponsor development: Companies that depend on both Wayland and KiCad can fund specific improvements

  3. Test and provide feedback: Help us identify which issues are most critical for your workflows

We fund some wxWidgets development to help improve Wayland compatibility, but many issues require broader changes in the Wayland ecosystem. We encourage contributions that can benefit all applications, not just KiCad.

Bottom Line

We try to be pragmatic. We support what works, we document what doesn’t, and we focus our development efforts where they’ll have most benefit for our users. We will adjust our position as Wayland improves, but we won’t compromise the reliability and functionality of KiCad.

For now, if you need to use KiCad on Linux, use X11.

The KiCad Development Team

Wayland