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

> Easily run X11 apps with Hyprland XWayland. This guide covers complete configuration for seamless integration, scaling, clipboard support, and coordinate translation on your Wayland desktop.

- Repository: [Hypr Development/Hyprland](https://github.com/hyprwm/Hyprland)
- Tags: how-to-guide
- Published: 2026-07-26

---

**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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/src/output/Monitor.hpp) and populated during monitor layout calculations in [`src/state/MonitorLayoutController.cpp`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/hyprland.conf) under the `xwayland` namespace:

```ini

# ~/.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`](https://github.com/hyprwm/Hyprland/blob/main/src/state/MonitorLayoutController.cpp) and [`src/render/Renderer.cpp`](https://github.com/hyprwm/Hyprland/blob/main/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:

```bash

# 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:

```ini

# 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`](https://github.com/hyprwm/Hyprland/blob/main/src/xwayland/Dnd.cpp) and the core data device implementation ([`src/protocols/core/DataDevice.cpp`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/src/xwayland/Dnd.cpp) and the core data device.
- **File Locations**: Key implementation files include [`src/xwayland/XWayland.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/xwayland/XWayland.cpp) (server startup), [`src/xwayland/XWM.cpp`](https://github.com/hyprwm/Hyprland/blob/main/src/xwayland/XWM.cpp) (surface management), and [`src/managers/XWaylandManager.cpp`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/hyprland.conf), or build Hyprland without XWayland support at compile time. When disabled, the `CXWayland` initialization is skipped in [`src/xwayland/XWayland.cpp`](https://github.com/hyprwm/Hyprland/blob/main/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`](https://github.com/hyprwm/Hyprland/blob/main/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.