Hyprland Setup Guide: Install and Configure (2026)

Posted: April 13, 2026 to Technology.

Hyprland is a dynamic tiling Wayland compositor for Linux that combines the keyboard-driven efficiency of tiling window managers with smooth animations, rounded corners, and visual polish that you normally only see in full desktop environments. If you have been stuck choosing between productivity (i3, Sway) and aesthetics (GNOME, KDE), Hyprland eliminates that trade-off. This guide covers everything from installation to advanced configuration, drawn from our team's daily experience running Wayland compositors on production workstations.

At Petronella Technology Group, our engineering team runs Linux daily. Our workstations use NixOS with Wayland compositors for security research, AI development, and infrastructure management. We wrote this guide because we have configured Hyprland alongside other compositors and understand the real-world setup challenges, especially with NVIDIA hardware.

What Is Hyprland

Hyprland is a dynamic tiling Wayland compositor written in C++ by Vaxry. Unlike traditional X11 window managers, Hyprland runs natively on the Wayland display protocol, which means better security isolation between applications, smoother rendering through direct GPU composition, and no legacy X11 baggage. It launched in 2022 and has since become one of the most actively developed window managers in the Linux ecosystem, with a growing community and a plugin system that extends its capabilities well beyond basic window management.

The word "dynamic" is important. Hyprland supports multiple tiling layouts (dwindle and master-stack) but also lets you float windows, group them into tabs, and switch layouts per-workspace. You get the discipline of tiling when you want focus, and the flexibility of floating when a dialog or reference window needs to sit on top. Animations between states are GPU-accelerated and configurable down to individual bezier curves.

Hyprland uses its own configuration format (hyprland.conf) rather than i3-compatible syntax. This is a deliberate design choice that allows features like per-monitor workspaces, window rules with regex matching, and animation definitions that would be awkward or impossible in i3/Sway config syntax.

Why Choose Hyprland Over i3, Sway, or GNOME

Every window manager involves trade-offs. Here is how Hyprland compares to the most common alternatives and where it genuinely excels.

Hyprland vs Sway

Sway is the closest comparison because both are Wayland-native tiling compositors. Sway aims for i3 compatibility and stability above all else. It is mature, well-tested, and ships in nearly every distribution. Hyprland trades some of that stability for features that Sway deliberately avoids: window animations, blur effects, rounded corners, gradients on borders, and a plugin API. If you want a compositor that looks and feels like a polished desktop while keeping tiling efficiency, Hyprland delivers that. If you want rock-solid stability with no visual frills, Sway is the safer bet.

Hyprland vs i3

i3 is X11-only. If you are starting fresh in 2026, there is little reason to begin with X11 unless you depend on specific X11-only applications. Hyprland supports XWayland for legacy X11 apps, so most software that ran under i3 will run under Hyprland. The configuration syntax is different, so there is no direct config migration, but the mental model of workspaces, keybindings, and tiling translates directly.

Hyprland vs GNOME or KDE

Full desktop environments provide a complete out-of-box experience: settings GUIs, integrated file managers, notification centers, and accessibility features. They are the right choice for users who do not want to assemble their desktop from individual components. Hyprland is for people who prefer to choose each piece (bar, launcher, notification daemon, lock screen) and configure them to work exactly how they want. The result is a leaner system that uses less memory, starts faster, and does precisely what you tell it to.

Installation: Arch, NixOS, and Fedora

Arch Linux

Arch is the most straightforward installation path. Hyprland is in the official repositories:

sudo pacman -S hyprland

This pulls in wlroots and all required dependencies. For the latest features, you can install hyprland-git from the AUR, though the stable release is recommended for daily driving. You will also want a few companion packages immediately:

sudo pacman -S kitty waybar wofi dunst

This gives you a terminal emulator (kitty), a status bar (waybar), an application launcher (wofi), and a notification daemon (dunst). These are not hard dependencies, but Hyprland does not bundle them, and you will want them before your first login.

NixOS

NixOS handles Hyprland through either the official module or the community flake. The declarative approach means your entire compositor configuration can be version-controlled and reproduced on any machine. In your NixOS configuration:

# configuration.nix
programs.hyprland = {
  enable = true;
  xwayland.enable = true;
};

# For NVIDIA (see NVIDIA section below)
hardware.nvidia = {
  modesetting.enable = true;
  open = true;
};
hardware.graphics.enable = true;

Home Manager integration is available through the wayland.windowManager.hyprland module, which lets you manage your hyprland.conf declaratively in Nix syntax. This is the approach our team uses because it keeps compositor configuration in the same flake as the rest of the system, making workstation rebuilds predictable. For more on how we use NixOS in production, see our NixOS AI infrastructure overview.

Fedora

Fedora packages Hyprland in the official repositories starting with Fedora 39:

sudo dnf install hyprland

On Fedora, SELinux is enabled by default, which occasionally causes issues with custom scripts or socket access. If you hit "permission denied" errors on Hyprland IPC sockets, check ausearch -m avc for denials and create a local policy module to allow them.

Other Distributions

Hyprland is also packaged for openSUSE Tumbleweed, Gentoo, and Void Linux. For distributions without a package, building from source requires meson, ninja, wlroots 0.18+, and a C++23 compiler. The Hyprland wiki maintains up-to-date build instructions for each platform.

Essential Configuration

Hyprland reads its configuration from ~/.config/hypr/hyprland.conf. The file is plain text with a clear section-based syntax. Unlike i3 config, Hyprland uses a keyword-value format with nested blocks for complex settings. Here is a practical starting configuration that covers the essentials:

Monitor Setup

# Set your monitor resolution and position
# Format: monitor = name, resolution@rate, position, scale
monitor = DP-1, 2560x1440@165, 0x0, 1
monitor = HDMI-A-1, 1920x1080@60, 2560x0, 1

# Fallback for any unrecognized monitor
monitor = , preferred, auto, 1

Use hyprctl monitors to list connected displays and their names. Multi-monitor support is a Hyprland strength: each monitor gets independent workspaces by default, and you can bind keys to move windows between monitors or swap monitor outputs.

Keybindings

# Set mod key (SUPER = Windows/Meta key)
$mod = SUPER

# Core bindings
bind = $mod, Return, exec, kitty
bind = $mod, D, exec, wofi --show drun
bind = $mod, Q, killactive
bind = $mod, F, fullscreen, 0
bind = $mod, V, togglefloating
bind = $mod SHIFT, E, exit

# Focus movement (vim-style)
bind = $mod, H, movefocus, l
bind = $mod, L, movefocus, r
bind = $mod, K, movefocus, u
bind = $mod, J, movefocus, d

# Move windows
bind = $mod SHIFT, H, movewindow, l
bind = $mod SHIFT, L, movewindow, r
bind = $mod SHIFT, K, movewindow, u
bind = $mod SHIFT, J, movewindow, d

# Workspaces
bind = $mod, 1, workspace, 1
bind = $mod, 2, workspace, 2
bind = $mod, 3, workspace, 3
bind = $mod, 4, workspace, 4
bind = $mod, 5, workspace, 5

# Move window to workspace
bind = $mod SHIFT, 1, movetoworkspace, 1
bind = $mod SHIFT, 2, movetoworkspace, 2
bind = $mod SHIFT, 3, movetoworkspace, 3
bind = $mod SHIFT, 4, movetoworkspace, 4
bind = $mod SHIFT, 5, movetoworkspace, 5

# Resize with mod + right mouse button
bindm = $mod, mouse:273, resizewindow
bindm = $mod, mouse:272, movewindow

Window Appearance

general {
    gaps_in = 5
    gaps_out = 10
    border_size = 2
    col.active_border = rgba(33ccffee) rgba(00ff99ee) 45deg
    col.inactive_border = rgba(595959aa)
    layout = dwindle
}

decoration {
    rounding = 10
    blur {
        enabled = true
        size = 6
        passes = 3
        new_optimizations = true
    }
    shadow {
        enabled = true
        range = 8
        render_power = 2
    }
}

animations {
    enabled = true
    bezier = ease, 0.25, 0.1, 0.25, 1.0
    animation = windows, 1, 4, ease
    animation = fade, 1, 4, ease
    animation = border, 1, 6, ease
    animation = workspaces, 1, 4, ease
}

The configuration is hot-reloaded. Save the file and changes apply immediately, no restart required. This makes iterating on your setup fast and forgiving.

Window Rules

Window rules let you control how specific applications behave. This is essential for apps that do not play well with tiling:

# Float file dialogs
windowrulev2 = float, title:^(Open File)(.*)$
windowrulev2 = float, title:^(Save As)(.*)$

# Float system monitors
windowrulev2 = float, class:^(pavucontrol)$

# Force specific apps to workspaces
windowrulev2 = workspace 3, class:^(firefox)$
windowrulev2 = workspace 4, class:^(Slack)$

# Make picture-in-picture always on top
windowrulev2 = float, title:^(Picture-in-Picture)$
windowrulev2 = pin, title:^(Picture-in-Picture)$
windowrulev2 = size 480 270, title:^(Picture-in-Picture)$

Must-Have Plugins and Companion Tools

Hyprland's ecosystem includes official companion tools and a growing library of third-party plugins. These are the ones worth installing immediately:

Official Hypr Ecosystem

• hyprpaper - Wallpaper utility with per-monitor support and preloading. Lightweight and fast, it handles static wallpapers without the overhead of a full image viewer.
• hyprlock - Screen lock with blur, gradient backgrounds, and input feedback animations. Replaces swaylock with Hyprland-native rendering.
• hypridle - Idle management daemon that triggers actions (lock screen, DPMS off, suspend) after configurable timeouts. Works with hyprlock for a complete lock-on-idle workflow.
• hyprpicker - Color picker that works correctly under Wayland. X11 color pickers cannot capture Wayland surfaces, so this fills a real gap for designers and developers.
• hyprshot - Screenshot utility supporting region, window, and monitor capture with annotation support.

Community Essentials

• Waybar - The standard status bar for Wayland compositors. Highly customizable with CSS, supports modules for workspaces, system tray, clock, battery, network, and custom scripts.
• Wofi or Rofi (Wayland fork) - Application launchers. Wofi is Wayland-native; rofi has a Wayland-compatible fork called rofi-wayland with more features and themes.
• Dunst or Mako - Notification daemons. Dunst is feature-rich with per-app rules; Mako is lighter with a cleaner default look.
• wl-clipboard - Clipboard utilities (wl-copy, wl-paste) that replace xclip/xsel for Wayland.
• grim + slurp - Screenshot (grim) and region selection (slurp) tools. Combine them for region screenshots: grim -g "$(slurp)" screenshot.png

Hyprland Plugin System

Hyprland supports C++ plugins loaded at runtime via hyprpm (Hyprland Plugin Manager). Notable plugins include:

• hyprbars - Adds title bars to windows (useful for floating windows or when you want visual window identification).
• hyprexpo - Workspace overview that shows all workspaces in a grid, similar to GNOME Activities or macOS Mission Control.
• hyprtrails - Adds a trailing effect to moving windows. Purely cosmetic, but popular in desktop showcases.

# Install a plugin
hyprpm add https://github.com/hyprwm/hyprland-plugins
hyprpm enable hyprbars

Plugins must be compiled against your exact Hyprland version. After updating Hyprland, rebuild plugins with hyprpm update.

NVIDIA GPU Setup

NVIDIA on Wayland has been one of the most-searched pain points in the Linux desktop space, and for good reason. NVIDIA's proprietary driver historically lacked the GBM (Generic Buffer Manager) backend that Wayland compositors require. As of driver version 535+ and the open kernel modules, the situation has improved substantially, but configuration still matters. Our team runs NVIDIA GPUs for AI workloads and has worked through these issues firsthand.

Driver Requirements

You need NVIDIA driver version 535 or later. Version 555+ is recommended for the best Wayland experience. Use the open kernel modules (nvidia-open) on Turing (RTX 20-series) or newer GPUs. Pre-Turing cards should use the proprietary modules.

Kernel Parameters

Add these to your bootloader configuration (GRUB, systemd-boot, or NixOS boot.kernelParams):

nvidia_drm.modeset=1
nvidia_drm.fbdev=1

On NixOS, this is handled declaratively:

boot.kernelParams = [ "nvidia_drm.modeset=1" "nvidia_drm.fbdev=1" ];

Environment Variables

Add these to your hyprland.conf or shell profile:

env = LIBVA_DRIVER_NAME,nvidia
env = XDG_SESSION_TYPE,wayland
env = GBM_BACKEND,nvidia-drm
env = __GLX_VENDOR_LIBRARY_NAME,nvidia
env = NVD_BACKEND,direct

Common NVIDIA Issues and Fixes

Flickering or black frames: Usually caused by missing nvidia_drm.modeset=1. Verify with cat /sys/module/nvidia_drm/parameters/modeset (should return Y).

Slow application launches: Some Electron and Chromium-based apps default to software rendering on Wayland. Add --ozone-platform=wayland and --enable-features=VaapiVideoDecodeLinuxGL to their launch flags.

Screen tearing: Enable misc:vfr = true (variable frame rate) in hyprland.conf. This allows the compositor to skip rendering unchanged frames, which reduces tearing and saves power.

Suspend/resume crashes: Add options nvidia NVreg_PreserveVideoMemoryAllocations=1 to /etc/modprobe.d/nvidia.conf and enable nvidia-suspend.service, nvidia-resume.service, and nvidia-hibernate.service via systemd.

Multi-GPU (hybrid) laptops: If you have an Intel/AMD iGPU alongside an NVIDIA dGPU, you may need env = AQ_DRM_DEVICES,/dev/dri/card1 to select the correct GPU. List devices with ls /dev/dri/ and match against lspci | grep VGA.

For additional context on NVIDIA hardware performance across different GPU tiers, our RTX 5090 vs A100 vs H100 comparison covers the compute capabilities relevant to both AI workloads and desktop compositing.

Theming and Rice

"Ricing" is the Linux community's term for customizing the look and feel of your desktop. Hyprland is one of the most riceable compositors available because it exposes fine-grained control over every visual element.

Popular Color Schemes

Catppuccin is currently the most popular theme in the Hyprland community. It is a pastel palette available in four flavors (Latte, Frappe, Macchiato, Mocha) with consistent ports for Hyprland, Waybar, kitty, rofi, dunst, and most terminal applications. To apply Catppuccin Mocha to Hyprland:

# In hyprland.conf
source = ~/.config/hypr/catppuccin-mocha.conf

general {
    col.active_border = $mauve $blue 45deg
    col.inactive_border = $surface0
}

Tokyo Night uses a deep navy and purple palette inspired by Tokyo's nightlife. It is popular for its readability and consistency across applications.

Nord is a cooler, arctic-inspired palette that pairs well with minimal setups. It has been around longer and has broad application support.

Gruvbox uses warm, retro-inspired tones. It is a proven choice that reduces eye strain for long coding sessions.

Waybar Customization

Waybar is styled entirely with CSS, which means you can achieve virtually any look. A minimal Waybar configuration:

// ~/.config/waybar/config.jsonc
{
    "layer": "top",
    "modules-left": ["hyprland/workspaces"],
    "modules-center": ["clock"],
    "modules-right": ["pulseaudio", "network", "battery", "tray"],
    "clock": {
        "format": "{:%H:%M  %a %d %b}",
        "tooltip-format": "{:%Y-%m-%d}"
    }
}

Wallpaper Tools

Beyond hyprpaper for static wallpapers, swww supports animated wallpaper transitions (fade, wipe, grow) and can cycle through a wallpaper directory on a timer. The mpvpaper tool plays video wallpapers using mpv, though this uses more GPU resources.

Performance Tips and Troubleshooting

Compositor Performance

Hyprland is generally lightweight, but blur and shadow effects consume GPU cycles. If you notice frame drops on older hardware:

• Reduce blur passes from 3 to 1 or disable blur entirely (decoration:blur:enabled = false).
• Disable shadows (decoration:shadow:enabled = false).
• Reduce animation duration or disable animations (animations:enabled = false).
• Enable misc:vfr = true to avoid rendering when nothing changes.

Memory Usage

A typical Hyprland session with Waybar, dunst, and hyprpaper uses 150-250 MB of RAM total. Compare this to GNOME Shell at 800+ MB or KDE Plasma at 500+ MB. The savings come from running only the components you choose.

XWayland Applications

Most X11 applications run under XWayland automatically. Known issues include:

• Blurry rendering on HiDPI: XWayland applications may render at 1x and then get upscaled. Set xwayland:force_zero_scaling = true in hyprland.conf and handle per-app scaling via environment variables (e.g., GDK_SCALE=2 for GTK apps).
• Screen sharing: Wayland screen sharing requires PipeWire and xdg-desktop-portal-hyprland. Install both and ensure PipeWire is running before attempting screen shares in browsers or video conferencing tools.

Debugging

Hyprland provides extensive runtime inspection via hyprctl:

# List all windows and their properties
hyprctl clients

# Check active configuration
hyprctl getoption general:border_size

# Monitor compositor performance
hyprctl monitors

# Reload configuration
hyprctl reload

# Check Hyprland version and build info
hyprctl version

Logs are written to /tmp/hypr/$HYPRLAND_INSTANCE_SIGNATURE/hyprland.log. Check this file first when troubleshooting crashes or rendering issues.

Why We Run Wayland for Security Work

This is not just a cosmetic choice for our team. Wayland's security model is fundamentally different from X11, and that matters when you work with sensitive client data, AI systems on Linux, and cybersecurity tooling.

Under X11, any application can read keystrokes from any other application, capture the screen contents of any window, and inject input events into other programs. This is not a bug; it is how the X11 protocol works. A compromised browser plugin under X11 can silently log passwords typed into your terminal. Keyloggers are trivial to write because X11 hands them the data by design.

Wayland isolates applications from each other. A Wayland client cannot see other clients' windows, read their input, or inject events into them. Screen capture and input simulation require explicit user consent through desktop portal protocols. This is the same security principle behind mobile operating systems, and it significantly raises the bar for local privilege escalation and information theft.

For an IT services firm handling CMMC assessments, HIPAA-regulated data, and digital forensics, running a display protocol that prevents casual cross-application snooping is a practical security measure, not a theoretical one. Combined with our AI services infrastructure, Wayland compositors provide the isolation guarantees we need when running sensitive workloads side by side.

Frequently Asked Questions

Is Hyprland stable enough for daily use?

Yes, with caveats. The stable releases (tagged versions in your package manager) are reliable for daily work. The git/development branch can introduce regressions. If you depend on your workstation for production work, stick to stable releases and update deliberately. Our team has run Hyprland and other Wayland compositors daily for over a year without workflow-interrupting crashes.

Can I use Hyprland with AMD GPUs?

AMD GPUs work excellently with Hyprland. The open-source amdgpu kernel driver and Mesa userspace driver provide full Wayland support out of the box, including hardware video decode and proper Vulkan rendering. AMD is the path of least resistance for Wayland in general.

Does screen sharing work in Zoom, Teams, and Google Meet?

Yes, but it requires xdg-desktop-portal-hyprland and PipeWire. Once installed, Chromium-based browsers and Electron apps can share individual windows or your full screen. Firefox also supports PipeWire screen capture. Make sure to select "Entire Screen" or a specific window in the portal dialog.

How do I switch from i3 or Sway?

There is no automated config migration tool. The concepts translate directly (workspaces, keybindings, window rules), but the syntax is different. Start with the example configuration above, map your existing keybindings to Hyprland syntax, and add window rules as you encounter applications that need them. Most users complete the transition in a weekend.

What about gaming?

Gaming under Hyprland works well for native Wayland titles and through XWayland for Steam/Proton games. Ensure you have a recent Mesa (AMD) or NVIDIA driver (555+). For competitive gaming where every frame matters, set misc:no_direct_scanout = false and consider disabling compositor effects during gameplay with a keybinding.

Will Hyprland work on my laptop?

Laptops work well, including touchpad gestures, lid close actions, and brightness controls. Configure touchpad settings in hyprland.conf under the input:touchpad section. For hybrid GPU laptops (Intel/AMD + NVIDIA), see the NVIDIA section above for the AQ_DRM_DEVICES configuration.

Getting Started

The fastest path from zero to a working Hyprland desktop is: install Hyprland and companion packages, copy the configuration examples from this guide into ~/.config/hypr/hyprland.conf, log into a TTY, and run Hyprland. Spend your first session adjusting keybindings and window rules to match your workflow. Add theming and visual polish after the fundamentals feel right.

If you are setting up Linux workstations for your organization and want professional guidance on desktop environment selection, security hardening, or GPU configuration for AI workloads, contact our team for a consultation.

About the Author: Craig Petronella is the CEO of Petronella Technology Group, a cybersecurity and IT infrastructure firm in Raleigh, NC. With CMMC-RP, CCNA, CWNE, and DFE certifications and over 30 years in IT, Craig's team runs NixOS and Wayland compositors daily for security research and AI development.

Related Guides

• Niri: Scrollable Tiling Wayland Compositor Guide -- another Wayland-native tiling compositor with a different workflow philosophy.
• Nerd Fonts: Complete Install and Setup Guide -- pair your Hyprland setup with patched fonts for terminal and status bar icons.
• Tokyo Night Theme Setup Guide -- apply a consistent color theme across Hyprland, your terminal, and your editor.
• Material Shell for GNOME: Tiling Made Simple -- an alternative approach to tiling for users who prefer GNOME.
• Migrate VMware to Proxmox: Complete Guide -- build your Linux-first virtualization stack.