Can I run Hyprland on NVIDIA hardware?

Yes, but you need the proprietary driver version 535 or newer, the kernel parameter nvidia-drm.modeset=1 set persistently, and the env variables LIBVA_DRIVER_NAME=nvidia and GBM_BACKEND=nvidia-drm exported in your Hyprland config. Expect occasional tearing or cursor glitches depending on driver version.

Does Hyprland work with a display manager like SDDM or GDM?

SDDM on Wayland works well. Add a Hyprland desktop entry at /usr/share/wayland-sessions/hyprland.desktop if your package does not include one. GDM works but is less tested; logging in from a TTY remains the most reliable method.

How do I take screenshots in Hyprland?

Use grim for full-screen capture and slurp to select a region: bind a key to 'grim -g "$(slurp)" ~/screenshots/$(date +%s).png' in your hyprland.conf bind= lines. The output goes to ~/screenshots/ by default.

What is the difference between exec and exec-once in hyprland.conf?

exec-once runs a command only on the first start of Hyprland, making it suitable for daemons like waybar or swww-daemon. exec runs on every config reload, which is useful for one-shot setup commands that need to re-apply after changes.

How do I make Hyprland start automatically on login without a display manager?

Add a conditional at the end of your ~/.bash_profile or ~/.zprofile: if [ -z "$DISPLAY" ] && [ "$XDG_VTNR" -eq 1 ]; then exec Hyprland; fi. This launches Hyprland automatically when you log into TTY1.

Install and Customise Hyprland

Hyprland is a dynamic tiling Wayland compositor built on wlroots that trades the spartan defaults of dwl or sway for rich animations, rounded corners, and a powerful configuration language — all without sacrificing keyboard-driven efficiency. It ships no display manager dependency, no mandatory status bar, and no hand-holding: you wire everything together yourself. That freedom is the point. This guide walks through a clean install on Arch and Fedora, a working hyprland.conf, animation tuning, ricing fundamentals, and using the Hyprland IPC socket to script your compositor.

Prerequisites and Wayland Basics

Hyprland requires a GPU with good Wayland support. AMD (radeonsi) and Intel (iris) work out of the box. NVIDIA requires the proprietary driver ≥ 535 with nvidia-drm.modeset=1 set as a kernel parameter; expect occasional rough edges. You also need a TTY login — Hyprland launches from a bare terminal, not an X session.

Confirm your kernel supports KMS: cat /sys/module/drm/parameters/edid_firmware should not error.
You do not need Xorg installed, but xwayland is recommended for legacy apps.
A working $XDG_RUNTIME_DIR is set automatically when you log in via a systemd user session (standard on both Arch and Fedora).

Installation

Arch Linux

Hyprland is in the official extra repository since late 2023. Install it along with a minimal but functional supporting stack:

sudo pacman -S hyprland xorg-xwayland kitty waybar wofi \
  pipewire pipewire-pulse wireplumber \
  polkit-kde-agent qt5-wayland qt6-wayland \
  xdg-desktop-portal-hyprland grim slurp wl-clipboard

kitty is the default terminal referenced by the starter config. waybar provides a status bar, wofi an application launcher, and grim/slurp handle screenshots. xdg-desktop-portal-hyprland is required for screen sharing via PipeWire.

Fedora

Fedora 39+ ships Hyprland in the official repos via the COPR maintained by solopasha, which tracks releases more closely than the base repo. On Fedora 40+ you can also check dnf directly first:

sudo dnf install hyprland kitty waybar wofi \
  pipewire pipewire-pulseaudio wireplumber \
  polkit xdg-desktop-portal-hyprland \
  grim slurp wl-clipboard xorg-x11-server-Xwayland

If the version in the base repo is stale (check with dnf info hyprland), add the COPR:

sudo dnf copr enable solopasha/hyprland
sudo dnf upgrade hyprland

First Launch

Log into a bare TTY (Ctrl+Alt+F2) and start Hyprland directly. Do not run it as root.

Hyprland

Hyprland writes its socket to /run/user/$UID/hypr/ and logs to $XDG_RUNTIME_DIR/hypr/$HYPRLAND_INSTANCE_SIGNATURE/hyprland.log. If the compositor crashes before rendering, that log is your first stop.

Core Configuration: hyprland.conf

Hyprland reads ~/.config/hypr/hyprland.conf. If it does not exist, a starter config is copied from /usr/share/hyprland/hyprland.conf. Copy it first:

mkdir -p ~/.config/hypr
cp /usr/share/hyprland/hyprland.conf ~/.config/hypr/hyprland.conf

Monitor Layout

Define monitors with the monitor keyword. Resolution, refresh rate, position, and scale are all set here:

# ~/.config/hypr/hyprland.conf
monitor=DP-1,2560x1440@144,0x0,1
monitor=HDMI-A-1,1920x1080@60,2560x0,1
# Catch-all for any unrecognised output:
monitor=,preferred,auto,1

Run hyprctl monitors inside an active session to find your output names and current modes.

Input Devices

input {
    kb_layout = us
    follow_mouse = 1
    touchpad {
        natural_scroll = true
        tap-to-click = true
    }
    sensitivity = 0   # -1.0 to 1.0, 0 means no acceleration curve
}

Window Rules and Workspace Pinning

Window rules target apps by class or title. Retrieve a window's class with hyprctl clients or the hyprprop tool:

windowrulev2 = float, class:^(pavucontrol)$
windowrulev2 = size 800 500, class:^(pavucontrol)$
windowrulev2 = workspace 2 silent, class:^(firefox)$
windowrulev2 = opacity 0.92 0.85, class:^(kitty)$

The two opacity values are active and inactive opacity respectively.

Animations and Eye Candy

Hyprland's animation system is curve-based. Every animation takes a bezier curve name, a duration in milliseconds, and an optional style. Define your curves first, then reference them:

animations {
    enabled = true

    bezier = overshot,  0.05, 0.9,  0.1, 1.05
    bezier = smoothOut, 0.5,  0,    0.99, 0.99
    bezier = smoothIn,  0.5, -0.5,  0.1,  1.5

    animation = windows,     1, 5,  overshot, slide
    animation = windowsOut,  1, 4,  smoothOut, slide
    animation = windowsMove, 1, 4,  smoothIn
    animation = border,      1, 5,  default
    animation = fade,        1, 5,  smoothIn
    animation = fadeDim,     1, 5,  smoothIn
    animation = workspaces,  1, 6,  overshot, slidevert
}

Reduce duration values (third argument) or set enabled = false for a snappier feel. The slidevert style on workspaces gives a macOS-like vertical swipe.

Decoration: Blur, Rounding, Shadows

general {
    gaps_in  = 5
    gaps_out = 10
    border_size = 2
    col.active_border   = rgba(cba6f7ff) rgba(89b4faff) 45deg
    col.inactive_border = rgba(595959aa)
    layout = dwindle
}

decoration {
    rounding = 10
    blur {
        enabled  = true
        size     = 6
        passes   = 3
        new_optimizations = true
    }
    drop_shadow  = true
    shadow_range = 12
    shadow_color = rgba(1a1a1aee)
}

Blur is GPU-intensive; reduce passes to 1 or 2 if compositing feels sluggish. The gradient border syntax accepts any number of colour stops and an angle.

Ricing: Status Bar, Wallpaper, and Theming

Wallpaper with hyprpaper or swww

swww supports smooth animated transitions between wallpapers. Install it (pacman -S swww on Arch or build from the AUR/COPR), then launch its daemon via an exec-once entry in your config:

exec-once = swww-daemon
exec-once = swww img ~/wallpapers/forest.jpg --transition-type wipe --transition-duration 2

Waybar Configuration

Waybar reads ~/.config/waybar/config and ~/.config/waybar/style.css. Launch it from Hyprland:

exec-once = waybar

For Hyprland-specific workspace modules, use "hyprland/workspaces" in the bar's module list. Waybar communicates with Hyprland over the IPC socket automatically when it detects $HYPRLAND_INSTANCE_SIGNATURE.

GTK and Qt Theming

Set GTK theme, icon theme, and cursor via gsettings or the ~/.config/gtk-3.0/settings.ini file. Wayland apps do not read .Xresources:

gsettings set org.gnome.desktop.interface gtk-theme     'Catppuccin-Mocha-Standard-Mauve-Dark'
gsettings set org.gnome.desktop.interface icon-theme    'Papirus-Dark'
gsettings set org.gnome.desktop.interface cursor-theme  'Bibata-Modern-Ice'
gsettings set org.gnome.desktop.interface cursor-size   24

For Qt apps, set QT_QPA_PLATFORMTHEME=qt6ct in your environment and configure qt6ct separately. Add environment variables to Hyprland via:

env = QT_QPA_PLATFORMTHEME,qt6ct
env = XCURSOR_SIZE,24
env = MOZ_ENABLE_WAYLAND,1

Hyprland IPC

Every running Hyprland instance exposes a Unix socket at /run/user/$UID/hypr/$HYPRLAND_INSTANCE_SIGNATURE/.socket.sock (commands) and .socket2.sock (events). The hyprctl binary wraps the command socket:

# Query active window
hyprctl activewindow

# Move focus left
hyprctl dispatch movefocus l

# Reload config without restarting
hyprctl reload

# Get JSON list of all windows
hyprctl clients -j | jq '.[].class'

Listening to Events

The event socket streams newline-delimited events you can consume in a script. This example reacts whenever the active workspace changes:

#!/usr/bin/env bash
SOCKET="/run/user/$UID/hypr/$HYPRLAND_INSTANCE_SIGNATURE/.socket2.sock"
socat - UNIX-CONNECT:"$SOCKET" | while IFS= read -r event; do
    case "$event" in
        workspace*)
            ws=$(echo "$event" | cut -d'>' -f2)
            notify-send "Switched to workspace $ws"
            ;;
    esac
done

Install socat if it is not already present. This pattern underlies most third-party Hyprland bars and applets.

Verification

After editing hyprland.conf, reload without a full restart:

hyprctl reload

Check for config parse errors:

hyprctl getoption general:border_size

If the returned value matches what you set, the config is being read correctly. For a full session health check:

hyprctl systeminfo

This prints your Hyprland version, wlroots version, GPU, and whether hardware acceleration is active. Confirm renderer shows Vulkan or OpenGL and not a software fallback.

Troubleshooting

Black screen at launch: Check hyprland.log for DRM/KMS errors. On NVIDIA, verify /etc/modprobe.d/nvidia.conf contains options nvidia-drm modeset=1 fbdev=1 and that initramfs has been rebuilt (mkinitcpio -P on Arch, dracut --force on Fedora).
XWayland apps blurry on HiDPI: Set xwayland { force_zero_scaling = true } in hyprland.conf and export GDK_SCALE=2 for GTK apps.
Screen sharing not working: Ensure xdg-desktop-portal-hyprland is running (systemctl --user status xdg-desktop-portal-hyprland) and that no other portal implementation is conflicting. Only one portal should handle org.freedesktop.impl.portal.ScreenCast.
Waybar not showing Hyprland workspaces: The $HYPRLAND_INSTANCE_SIGNATURE environment variable must be in Waybar's environment. Launch it via exec-once in hyprland.conf, not from a separate systemd user service, unless you pass the environment explicitly with systemctl --user import-environment.
Config changes not applying after reload: Some options (monitor layout changes, certain input options) require a full Hyprland restart. The wiki documents which keywords are hot-reloadable.