Hyprland 0.55+ on Debian 13 (Trixie) with Backports and Quickshell

darth · September 15, 2026, 12:57pm

This guide installs a complete, usable Hyprland session on Debian 13: Hyprland,
Quickshell, wallpaper, locking and idle handling, a PolicyKit agent, blue-light
control, portals, screenshots, audio controls and a display manager entry.

The example files use the Lua configuration format introduced with Hyprland
0.55. They are cleaned versions of a real daily-driver setup: usernames,
absolute home paths, monitor names, GPU assumptions, keyboard locale,
Syncthing integration and machine-specific backlight/battery tooling have been
removed.

Tested package versions on 2026-09-15 included Hyprland 0.55.2 and Quickshell
0.3.0 from trixie-backports. Backports moves over time, so inspect the
candidate versions before installing.

Hyprland is a compositor, not a complete desktop environment. You have to
choose and configure the shell, launcher, locker, notification server,
portals and other components. This guide makes those choices for you, but it
is deliberately modular.

What this setup uses

Role	Program
Compositor	Hyprland 0.55.2
Desktop bar and notifications	Quickshell
Application launcher	Hyprlauncher
Terminal	Kitty
File manager	Dolphin
Wallpaper	Hyprpaper
Idle daemon and locker	Hypridle + Hyprlock
PolicyKit prompt	Hyprpolkitagent
Blue-light control	Hyprsunset
Screen sharing portal	xdg-desktop-portal-hyprland
File chooser fallback	xdg-desktop-portal-gtk
Screenshots	Grim + Slurp + wl-clipboard
Audio	PipeWire + WirePlumber (`wpctl`)
Login manager	SDDM (optional)

1. Confirm that the system is Trixie

Do not use these repository lines on Debian 12 or a derivative without first
adapting them to that distribution.

cat /etc/os-release

The expected content is Debian 13 with codename trixie. Mine was version 13.7 at the time of this document. Fully update the base system before adding Backports:

sudo apt update
sudo apt full-upgrade

Reboot first if that command installed a new kernel, graphics stack or systemd.

2. Enable Trixie Backports

Debian recommends opting into individual backported packages instead of
globally assigning Backports a high APT priority. Create a deb822 source file:

sudo tee /etc/apt/sources.list.d/debian-backports.sources >/dev/null <<'EOF'
Types: deb deb-src
URIs: https://deb.debian.org/debian
Suites: trixie-backports
Components: main
Enabled: yes
Signed-By: /usr/share/keyrings/debian-archive-keyring.gpg
EOF

sudo apt update

If you are doing a fresh Debian netinstall, you can do it via expert mode which will give you an opportunity to simply put one check mark on “backports” so that later you don’t have to add it manually.

Check what APT will select:

apt policy hyprland quickshell hyprpaper hypridle hyprlock

At the time of writing, the Lua config in this bundle requires Hyprland 0.55 or
newer. If APT offers 0.54 or older, do not install these example files unchanged.

3. Install Hyprland and its session components

Install the tightly coupled Hyprland ecosystem from the same Backports suite:

sudo apt install -t trixie-backports \
  hyprland hyprland-guiutils hyprlauncher \
  hyprpaper hypridle hyprlock hyprpolkitagent hyprsunset \
  xdg-desktop-portal-hyprland quickshell

Then install the ordinary Debian utilities used by the supplied configuration:

sudo apt install \
  kitty dolphin \
  xdg-desktop-portal xdg-desktop-portal-gtk qt6-wayland \
  pipewire wireplumber pavucontrol \
  network-manager network-manager-gnome iproute2 \
  grim slurp wl-clipboard libnotify-bin \
  brightnessctl playerctl htop xdg-user-dirs \
  fonts-jetbrains-mono python3

Notes:

brightnessctl controls supported laptop backlights. The bar hides that
widget when /sys/class/backlight is empty.
The bar uses NetworkManager when available and falls back to the system’s
default route for basic online/offline status.
Desktop systems without a battery simply do not display a battery widget.
Dolphin is optional in principle, but the supplied SUPER+E binding expects
it. Change fileManager in hyprland.lua if you prefer another program.
The Quickshell config is the notification server. Do not autostart Dunst,
Mako or another notification daemon at the same time unless you intentionally
remove the notification section from shell.qml.

Optional SDDM login manager

If the system does not already have a graphical login manager:

sudo apt install sddm
sudo systemctl enable sddm.service

Debian’s Hyprland package installs a Wayland session entry whose launcher is
/usr/bin/start-hyprland. SDDM should therefore offer Hyprland in its
session chooser after the next restart. If several display managers are
installed, select one with:

sudo dpkg-reconfigure sddm

The extras/sddm-nightshift directory contains an optional matching SDDM
theme. Inspect its installer before running it because it changes system-wide
files under /etc and /usr/share:

cd extras/sddm-nightshift
chmod +x install.sh
sudo ./install.sh

The installer backs up affected SDDM files under /var/backups/sddm-nightshift.
The theme is cosmetic and is not required for Hyprland.

4. Important Debian/systemd gotcha: `graphical-session.target`

On the tested Trixie Backports packages, installing Hyprpaper, Hypridle,
Hyprpolkitagent and Hyprsunset created global user-unit links under:

/etc/systemd/user/graphical-session.target.wants/

Their unit files use WantedBy=graphical-session.target and generally only
test whether WAYLAND_DISPLAY exists. The generic
graphical-session.target means any graphical session, not specifically
Hyprland. Consequently, these Hyprland utilities may also start when logging
into Plasma Wayland or another Wayland desktop.

Inspect the state after installing or upgrading the packages:

systemctl --global is-enabled \
  hyprpaper.service hypridle.service hyprpolkitagent.service hyprsunset.service

find /etc/systemd/user/graphical-session.target.wants \
  -maxdepth 1 -type l -name 'hypr*.service' -print

This bundle starts those programs directly from the Hyprland-only
hl.on("hyprland.start", ...) block, so disable the global links:

sudo systemctl --global disable \
  hyprpaper.service hypridle.service hyprpolkitagent.service hyprsunset.service

systemctl --user stop \
  hyprpaper.service hypridle.service hyprpolkitagent.service hyprsunset.service

systemctl --user daemon-reload

Run the check again after package upgrades. If a package repeatedly recreates
the links, report it to the Debian Backports maintainers and consider a global
mask only if you understand that it will also prevent starting those units via
systemctl --user:

sudo systemctl --global mask \
  hyprpaper.service hypridle.service hyprpolkitagent.service hyprsunset.service

Direct executable launches from hyprland.lua are unaffected by a systemd
unit mask. To undo it later, use the corresponding systemctl --global unmask
command.

Do not globally enable xdg-desktop-portal-hyprland. Portals are selected and
D-Bus-activated according to the current desktop session.

5. Install the supplied configuration

The bundle has this layout:

configs/
├── hypr/
│   ├── device-specific/
│   │   ├── input.lua
│   │   └── monitors.lua
│   ├── scripts/
│   │   └── screenshot-area.sh
│   ├── wallpapers/
│   │   └── README.md
│   ├── hypridle.conf
│   ├── hyprland.lua
│   ├── hyprlock.conf
│   └── hyprpaper.conf
└── quickshell/
    ├── components/Chip.qml
    ├── scripts/
    │   ├── brightness-cycle.py
    │   ├── brightness-watch.py
    │   └── status.py
    └── shell.qml

Back up existing files before copying anything:

backup_stamp=$(date +%Y%m%d-%H%M%S)
[ ! -d "$HOME/.config/hypr" ] || \
  cp -a "$HOME/.config/hypr" "$HOME/.config/hypr.backup-$backup_stamp"
[ ! -d "$HOME/.config/quickshell" ] || \
  cp -a "$HOME/.config/quickshell" "$HOME/.config/quickshell.backup-$backup_stamp"

install -d "$HOME/.config/hypr" "$HOME/.config/quickshell"
cp -a configs/hypr/. "$HOME/.config/hypr/"
cp -a configs/quickshell/. "$HOME/.config/quickshell/"
chmod +x "$HOME/.config/hypr/scripts/screenshot-area.sh"
chmod +x "$HOME/.config/quickshell/scripts/"*.py

The copy commands overwrite same-named files, which is why the backup step is
not optional for an existing setup.

Add a wallpaper

The image itself is intentionally not included. Copy any JPG, PNG, JXL or other
Hyprpaper-supported image to:

~/.config/hypr/wallpapers/wallpaper.jpg

Alternatively, edit hyprpaper.conf and point path at your own image.

Configure monitors and input

The supplied device-specific/monitors.lua is intentionally safe and generic:
it uses every display’s preferred mode, automatic position and automatic scale.
After the first successful login, inspect detected outputs:

hyprctl monitors all
hyprctl devices

Then add explicit monitor modes, positions, scales and per-device input options
to the two files in ~/.config/hypr/device-specific/. Keeping these settings
separate makes the main config portable between machines.

The keyboard defaults to US. Change these values in hyprland.lua as needed:

kb_layout = "us"
kb_variant = ""

6. Start Hyprland

The safest first test is from a text console so a compositor failure cannot
trap you in a broken graphical session:

Press Ctrl+Alt+F3 and log in.
Run start-hyprland.
Use SUPER+M to leave the session.

Once that works, select Hyprland from SDDM and log in normally.

Useful default bindings in this configuration:

Binding	Action
`SUPER+Q`	Kitty
`SUPER+E`	Dolphin
`SUPER+R`	Hyprlauncher
`SUPER+C`	Close the focused window
`SUPER+L`	Lock
`SUPER+M`	Exit Hyprland
`SUPER+1` … `SUPER+0`	Switch to workspaces 1 … 10
`SUPER+SHIFT+1` … `SUPER+SHIFT+0`	Move a window to a workspace
`SUPER+arrow`	Navigate the scrolling layout
`SUPER+CTRL+arrow`	Directional focus, including across monitors
`SUPER+left mouse`	Move a window
`SUPER+right mouse`	Resize a window
`Print`	Select an area, save it and copy it to the clipboard

7. Quickshell behavior and customization

The supplied shell creates one bar per monitor and includes:

workspace buttons and the active window title;
clock, CPU, RAM, network, volume, brightness and battery status;
an AWAKE toggle implemented with a Wayland idle inhibitor;
volume and brightness on-screen displays;
a notification server with clickable notification actions;
lock, launcher, network settings, mixer and process-viewer actions.

Test it manually inside Hyprland with:

quickshell -n -p "$HOME/.config/quickshell"

The main Hyprland configuration starts it automatically. If Quickshell exits,
run the command in a terminal and read its QML error output. Quickshell watches
its QML configuration and normally reloads it when a file changes.

The color palette is defined near the top of shell.qml and in
hyprlock.conf. The default font is JetBrains Mono.

8. Portals and screen sharing

XDPH supplies Hyprland-specific screen sharing and global shortcut portals, but
does not implement a file picker. That is why the install command also includes
xdg-desktop-portal-gtk.

Check portal logs after logging into Hyprland:

systemctl --user status xdg-desktop-portal.service
systemctl --user status xdg-desktop-portal-hyprland.service
journalctl --user -b -u xdg-desktop-portal-hyprland.service

If you also use Plasma and want KDE’s file picker in Hyprland, install
xdg-desktop-portal-kde and create
~/.config/xdg-desktop-portal/hyprland-portals.conf:

[preferred]
default = hyprland;gtk
org.freedesktop.impl.portal.FileChooser = kde

Log out and back in after changing portal selection. Killing portal processes
mid-session should be a troubleshooting step, not a permanent autostart hack.

9. NVIDIA notes

The supplied config intentionally contains no NVIDIA variables because they are
wrong for Intel/AMD systems and driver requirements change. Install a driver
using Debian’s current Trixie instructions, not NVIDIA’s .run installer, and
read Hyprland’s current NVIDIA page before adding compositor options.

At minimum, confirm DRM modesetting after rebooting:

cat /sys/module/nvidia_drm/parameters/modeset

It should print Y. The current Hyprland documentation recommends
options nvidia_drm modeset=1 when the driver does not enable it by default.
Driver branch, kernel, Secure Boot, hybrid-GPU routing and suspend support all
need to be handled according to the exact hardware; do not blindly copy an
NVIDIA block from somebody else’s configuration.

Only after confirming that the installed VA-API driver needs them should you
consider optional variables such as:

hl.env("LIBVA_DRIVER_NAME", "nvidia")
hl.env("__GLX_VENDOR_LIBRARY_NAME", "nvidia")
hl.env("NVD_BACKEND", "direct")

10. Validation and troubleshooting

Confirm versions and configuration errors

Hyprland --version
quickshell --version
hyprctl configerrors

Inspect the current session environment

printf '%s\n' "$XDG_CURRENT_DESKTOP" "$XDG_SESSION_DESKTOP" "$XDG_SESSION_TYPE"
systemctl --user show-environment | grep -E '^(WAYLAND_DISPLAY|XDG_CURRENT_DESKTOP|XDG_SESSION_DESKTOP|XDG_SESSION_TYPE)='

Expected Hyprland values include Hyprland and wayland. Stale values in the
user systemd manager can make D-Bus-activated desktop components select the
wrong backend.

Hyprland crashes or returns immediately

From a text console, preserve both the compositor output and this boot’s logs:

start-hyprland 2>&1 | tee "$HOME/hyprland-start.log"
journalctl --user -b > "$HOME/hyprland-user-journal.log"
journalctl -b | grep -iE 'hypr|drm|gpu|nvidia|amdgpu|i915' > "$HOME/hyprland-gpu.log"

Also inspect crash reports under ~/.cache/hyprland/ if that directory exists.
Temporarily move the config aside to distinguish a compositor/GPU failure from
a configuration failure:

mv "$HOME/.config/hypr" "$HOME/.config/hypr.test-backup"
start-hyprland

Hyprland will generate a minimal example when no config exists. Restore your
directory after the test:

[ ! -e "$HOME/.config/hypr" ] || \
  mv "$HOME/.config/hypr" "$HOME/.config/hypr.generated-test"
mv "$HOME/.config/hypr.test-backup" "$HOME/.config/hypr"

Do not report a configuration-induced crash without first reproducing it with
the generated minimal configuration.

Wallpaper, idle daemon or PolicyKit agent appears in Plasma

Revisit the graphical-session.target section. Check both system-wide and
per-user enablement:

systemctl --global is-enabled hyprpaper hypridle hyprpolkitagent hyprsunset
systemctl --user is-enabled hyprpaper hypridle hyprpolkitagent hyprsunset

Disable any generic graphical-session links and let hyprland.lua own their
startup.

Locking does nothing

hypridle.conf is required for Hypridle and hyprlock.conf is required for a
visible Hyprlock interface. Test both from inside Hyprland:

hyprlock --verbose
hypridle -v

The supplied policy locks after five minutes, turns displays off after ten
minutes, and does not suspend automatically. Edit the timeouts to taste.

No sound controls

wpctl status
systemctl --user status pipewire.service wireplumber.service

No brightness control

brightnessctl --list
ls -la /sys/class/backlight

External monitors normally require DDC/CI tooling instead of
brightnessctl; that is outside this generic configuration.

11. Updating

Backports are low priority by design. Packages already installed from
Backports receive updates from that suite, while unrelated stable packages
should remain on stable. Review planned changes before applying them:

sudo apt update
apt list --upgradable
sudo apt upgrade

After a Hyprland ecosystem upgrade, verify that versions are mutually
consistent and re-check the global user-unit links:

apt policy hyprland quickshell hyprpaper hypridle hyprlock hyprpolkitagent hyprsunset
systemctl --global is-enabled hyprpaper hypridle hyprpolkitagent hyprsunset

Avoid mixing hand-built Hyprland libraries, -git builds, Debian stable,
testing and Backports packages. The ecosystem has tightly coupled shared
libraries; mixed versions are a common cause of missing-symbol and .so
errors.

12. Rollback

To stop using the example configs, log into another session or a text console
and restore the backups created in section 5. To remove only the Backports
desktop components:

sudo apt remove \
  hyprland hyprland-guiutils hyprlauncher \
  hyprpaper hypridle hyprlock hyprpolkitagent hyprsunset \
  xdg-desktop-portal-hyprland quickshell
sudo apt autoremove

Removing Hyprland does not require removing SDDM, PipeWire, NetworkManager,
Dolphin or the generic portal because other desktops may use them.

Files

All files are on Linux Renaissance GIT. If you are an editor of this document and you wish to alter the files on the GIT you need to ask me for an account.