Skip to Content
getting-started-4ve214fQuick Start

Last Updated: 3/12/2026

Quick Start

Get Hyprland running and configured for your first session. This guide walks you through launching Hyprland, understanding the default keybindings, and creating your initial configuration.

Launching Hyprland

From a TTY

The simplest way to start Hyprland:

Hyprland

From a Display Manager

Select “Hyprland” from your display manager’s session list at login. The session file is installed to /usr/share/wayland-sessions/hyprland.desktop (or /usr/local/share/wayland-sessions/ depending on your install prefix).

With a Custom Config

Specify a configuration file:

Hyprland -c /path/to/your/hyprland.conf

Initial Configuration

Hyprland looks for its configuration at ~/.config/hypr/hyprland.conf. If this file doesn’t exist, Hyprland uses built-in defaults.

Creating Your First Config

Copy the example configuration:

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

Or if you installed with a custom prefix:

cp /usr/local/share/hypr/hyprland.conf ~/.config/hypr/hyprland.conf

Essential Keybindings

The example configuration sets $mainMod to SUPER (Windows key). Here are the essential keybindings to get started:

Window Management

  • SUPER + Q: Launch terminal (default: kitty)
  • SUPER + C: Close active window
  • SUPER + M: Exit Hyprland
  • SUPER + E: Launch file manager (default: dolphin)
  • SUPER + V: Toggle floating mode for active window
  • SUPER + R: Launch application menu (default: hyprlauncher)

Focus Movement

  • SUPER + Arrow Keys: Move focus between windows
  • SUPER + Left/Right/Up/Down: Navigate tiled windows

Workspaces

  • SUPER + [1-9, 0]: Switch to workspace 1-10
  • SUPER + SHIFT + [1-9, 0]: Move active window to workspace 1-10
  • SUPER + Mouse Scroll: Cycle through workspaces

Window Manipulation

  • SUPER + Left Mouse Button: Move window (drag)
  • SUPER + Right Mouse Button: Resize window (drag)

Configuration Basics

The configuration file uses a simple syntax. Here’s the structure:

# Comments start with #

# Set variables
$mainMod = SUPER
$terminal = kitty

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

# Keybindings
bind = $mainMod, Q, exec, $terminal
bind = $mainMod, C, killactive,

Live Reload

Hyprland automatically reloads your configuration when you save ~/.config/hypr/hyprland.conf. No need to restart.

Setting Your Preferred Apps

Edit these variables in your config:

$terminal = kitty        # Your preferred terminal
$fileManager = dolphin   # Your file manager
$menu = hyprlauncher     # Your app launcher

Common alternatives:

  • Terminal: alacritty, foot, wezterm
  • File Manager: nautilus, thunar, pcmanfm
  • App Launcher: wofi, rofi, fuzzel

Autostart Applications

Add programs to launch on startup:

exec-once = waybar        # Status bar
exec-once = hyprpaper     # Wallpaper
exec-once = nm-applet &   # Network manager applet

Troubleshooting

Black Screen on Launch

  • Check that your GPU drivers are installed
  • Verify OpenGL ES 3.0 support: glxinfo | grep "OpenGL ES"
  • Try launching from a TTY instead of a display manager

Keybindings Not Working

  • Ensure $mainMod is set correctly in your config
  • Check for conflicting keybindings
  • Verify the config file has no syntax errors

Apps Not Launching

  • Check that the applications are installed
  • Update the $terminal, $fileManager, and $menu variables to match your installed apps

What’s Next

InstallationKeybindings