How to Run X11 Apps with Hyprland XWayland: Complete Configuration Guide

Hyprland runs X11 applications through an embedded XWayland server that automatically bridges X11 clients to native Wayland surfaces with proper scaling, clipboard integration, and coordinate translation.

Hyprland provides first-class support for legacy X11 applications via its XWayland subsystem implemented in the hyprwm/Hyprland repository. When enabled, the compositor creates an internal X server that represents each X11 window as a CXWaylandSurface object mapped to a native Hyprland window, allowing X11 apps to participate in tiling, workspaces, and animations alongside Wayland clients.

How Hyprland Implements XWayland

Startup and Server Initialization

On compositor initialization, the CXWayland class creates a CXWaylandServer instance that launches the XWayland binary and establishes a Wayland client connection (m_xwaylandClient). This process is handled in src/xwayland/XWayland.cpp, where the server manages the lifecycle of the embedded X display.

Surface Creation and Window Mapping

When an X11 application creates a top-level window, the XWayland shell protocol notifies Hyprland's window manager. The CXWM::windowForXID method in src/xwayland/XWM.cpp instantiates a CXWaylandSurface object that wraps the X window ID and stores it in the m_surfaces collection.

The XWaylandManager (src/managers/XWaylandManager.cpp) then links this surface to a Hyprland CWindow via the m_xwaylandSurface member. This bridging forwards state changes—including size, geometry, and focus—from the XWayland surface to the Hyprland window, ensuring decorations and animations behave consistently with native Wayland windows.

Coordinate Translation and Scaling

Because XWayland uses logical coordinates while Hyprland may apply monitor scaling or transformations, the XWaylandManager::xwaylandToWaylandCoords function converts positions using each monitor's m_xwaylandPosition and m_xwaylandScale fields. These values are defined in src/output/Monitor.hpp and populated during monitor layout calculations in src/state/MonitorLayoutController.cpp, ensuring mouse and cursor events align correctly between X11 and Wayland coordinate spaces.

Enabling and Configuring XWayland

XWayland support is compiled by default but can be disabled at build time. Runtime configuration resides in your hyprland.conf under the xwayland namespace:

# ~/.config/hypr/hyprland.conf

xwayland:enabled = 1          # 1 = enabled, 0 = completely disable XWayland

xwayland:force_zero_scaling = 0   # 1 = force XWayland scale to 1 (recommended for HiDPI)

xwayland:use_nearest_neighbor = 0 # 1 = use nearest-neighbor filtering for XWayland textures

The compositor reads these values via CConfigValue in src/state/MonitorLayoutController.cpp and src/render/Renderer.cpp. When force_zero_scaling is enabled, X11 applications use unscaled logical coordinates, preventing blurry rendering on high-density displays.

Running X11 Applications

Basic Launch

With XWayland enabled, launching X11 applications requires no additional steps:

# Install XWayland (usually provided by the xwayland package)

sudo pacman -S xwayland  # Arch Linux example

# Launch any X11 application

xeyes
gimp
xterm

The application automatically connects to the embedded X server (:0 by default), and Hyprland creates a corresponding window that can be tiled, floated, or moved across workspaces like any native Wayland client.

HiDPI Configuration

For high-resolution displays, configure XWayland to use logical scaling:

# Force XWayland to scale 1:1 with physical pixels

xwayland:enabled = 1
xwayland:force_zero_scaling = 1

This configuration ensures X11 applications render at native resolution without compositor scaling, while xwaylandToWaylandCoords handles the coordinate translation between X11's unscaled space and Hyprland's scaled output.

Clipboard and Drag-and-Drop

Clipboard and drag-and-drop operations are bridged between X11 and Wayland protocols in src/xwayland/Dnd.cpp and the core data device implementation (src/protocols/core/DataDevice.cpp). When the Wayland clipboard is accessed while an X client has focus, Hyprland checks g_pXWayland->m_server->m_xwaylandClient to route data appropriately, maintaining seamless copy-paste between X11 and Wayland applications.

Summary

• XWayland Architecture: Hyprland uses CXWayland and CXWM classes to manage an embedded X server, creating CXWaylandSurface objects that map to native CWindow instances.
• Configuration: Enable via xwayland:enabled = 1 in hyprland.conf, with force_zero_scaling recommended for HiDPI setups.
• Coordinate Handling: Automatic translation between X11 logical coordinates and Wayland scaled coordinates occurs via XWaylandManager::xwaylandToWaylandCoords using monitor-specific position and scale data.
• Data Bridge: Clipboard and drag-and-drop operate seamlessly across protocols through implementations in src/xwayland/Dnd.cpp and the core data device.
• File Locations: Key implementation files include src/xwayland/XWayland.cpp (server startup), src/xwayland/XWM.cpp (surface management), and src/managers/XWaylandManager.cpp (window bridging).

Frequently Asked Questions

Do I need to install XWayland separately?

Yes. While Hyprland includes the integration code, you must install the xwayland package from your distribution's repositories. Hyprland detects the binary at startup and initializes the CXWaylandServer only if the binary is present and xwayland:enabled is set to 1.

Why do my X11 apps look blurry on my 4K monitor?

XWayland defaults to scaled coordinates that match your monitor's DPI settings. Set xwayland:force_zero_scaling = 1 in your configuration to force X11 applications to use unscaled logical coordinates (1:1 pixel mapping). This prevents the compositor from scaling XWayland buffers, resulting in sharp text and UI elements at native resolution.

Can I completely disable XWayland support?

Yes. Set xwayland:enabled = 0 in your hyprland.conf, or build Hyprland without XWayland support at compile time. When disabled, the CXWayland initialization is skipped in src/xwayland/XWayland.cpp, and any attempt to launch X11 applications will fail to connect to a display server.

How does Hyprland handle input focus for XWayland windows?

Focus transitions are managed through the CXWM class in src/xwayland/XWM.cpp, which translates X11 focus events to Hyprland's native focus system. When you click an XWayland window, the manager updates the corresponding CWindow focus state and ensures keyboard input is routed through the correct protocol layer, maintaining consistency with native Wayland window focus behavior.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}