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

**URL:** <https://forum.linuxrenaissance.com/t/hyprland-0-55-on-debian-13-trixie-with-backports-and-quickshell/144>\
**Category:** Knowledge Base\
**Tags:** debian, hyprland, quickshell\
**Created:** [September 15, 2026, 12:57pm UTC](https://forum.linuxrenaissance.com/t/hyprland-0-55-on-debian-13-trixie-with-backports-and-quickshell/144 "2026-09-15T12:57:30Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![darth](https://forum.linuxrenaissance.com/user_avatar/forum.linuxrenaissance.com/darth/32/46_2.png) [@darth](https://forum.linuxrenaissance.com/u/darth)\
**Post date:** [September 15, 2026, 12:57pm UTC](https://forum.linuxrenaissance.com/t/hyprland-0-55-on-debian-13-trixie-with-backports-and-quickshell/144/1 "2026-09-15T12:57:30Z")

</div>

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.

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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`:

```bash
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:

```plaintext
/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:

```bash
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:

```bash
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`:

```bash
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:

```plaintext
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:

```bash
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:

```plaintext
~/.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:

```bash
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:

```lua
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:

1. Press `Ctrl+Alt+F3` and log in.
2. Run `start-hyprland`.
3. 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:

```bash
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:

```bash
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`:

```ini
[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:

```bash
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:

```lua
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

```bash
Hyprland --version
quickshell --version
hyprctl configerrors

```

### Inspect the current session environment

```bash
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:

```bash
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:

```bash
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:

```bash
[! -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:

```bash
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:

```bash
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

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

```

### No brightness control

```bash
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:

```bash
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:

```bash
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:

```bash
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](https://git.linuxrenaissance.com/darth/hyprland-055-trixie). If you are an editor of this document and you wish to alter the [files on the GIT](https://git.linuxrenaissance.com/darth/hyprland-055-trixie) you need to ask me for an account.

## Sources

- [Debian Backports instructions](https://backports.debian.org/Instructions/)
- [Debian package: Hyprland in Trixie Backports](https://packages.debian.org/trixie-backports/hyprland)
- [Debian package: Quickshell in Trixie Backports](https://packages.debian.org/trixie-backports/quickshell)
- [Quickshell 0.3 documentation](https://quickshell.org/docs/v0.3.0/)
- [Hyprland installation guide](https://wiki.hypr.land/Getting-Started/Installation/)
- [Hyprland Lua configuration start page](https://wiki.hypr.land/Configuring/Start/)
- [Hyprpaper documentation](https://wiki.hypr.land/hypr-ecosystem/user/hyprpaper/)
- [Hypridle documentation](https://wiki.hypr.land/hypr-ecosystem/user/hypridle/)
- [Hyprlock documentation](https://wiki.hypr.land/hypr-ecosystem/user/hyprlock/)
- [XDG Desktop Portal for Hyprland](https://wiki.hypr.land/Hypr-Ecosystem/xdg-desktop-portal-hyprland/)
- [Hyprland NVIDIA documentation](https://wiki.hypr.land/nvidia/)
- [Debian NVIDIA driver documentation](https://wiki.debian.org/NvidiaGraphicsDrivers)
- [Debian systemd `graphical-session.target` manual](https://manpages.debian.org/trixie/systemd/systemd.special.7.en.html)