Hyprland konfigurieren: Lua-Config, Tastenkürzel und Themes

Der große Reiz an Hyprland ist, dass sich praktisch alles ändern lässt: Tastenkürzel, Abstände, Animationen, Fensterregeln, Monitoranordnung. Der große Frust ist, dass dieselbe Freiheit den Einstieg unübersichtlich macht – zumal sich das Konfigurationsformat gerade grundlegend geändert hat.

Dieser Artikel zeigt, wo die Dateien liegen, wie die neue Lua-Konfiguration funktioniert und welche Änderungen sich zuerst lohnen. Grundlage ist Hyprland 0.56.2 auf Omarchy 4.0.3 (Stand September 2026).

Neu: Lua statt Schlüssel-Wert-Liste

Bis vor Kurzem war die Hyprland-Konfiguration eine einzige Datei hyprland.conf mit Zeilen wie bind = SUPER, RETURN, exec, foot. Diese Form funktioniert weiterhin – aktuelle Versionen bringen aber zusätzlich einen Lua-Parser mit, und neue Distributionen setzen darauf.

Der Unterschied ist mehr als Kosmetik: In Lua kannst du Schleifen schreiben, Variablen verwenden und Funktionen bauen. Die zehn Tastenkürzel für die zehn Arbeitsflächen sind damit keine zehn Zeilen mehr, sondern eine Schleife.

Das musst du wissen, bevor du Anleitungen aus dem Netz kopierst: Beide Formate gleichzeitig funktionieren nicht. Ein System nutzt entweder die eine oder die andere Form. Wenn eine Anleitung bind = ... zeigt und deine Datei o.bind("...") enthält, brauchst du die Lua-Schreibweise.

Wo die Dateien liegen

Alles steckt in ~/.config/hypr/. Auf einem Omarchy-System sieht das so aus:

Diese Trennung ist mehr wert, als sie aussieht: Die Vorgaben der Distribution liegen woanders, deine Änderungen werden danach geladen. Ein Systemupdate kann also die Vorgaben verbessern, ohne deine Anpassungen zu überschreiben.

Die erste Änderung: Ein eigenes Tastenkürzel

Öffne ~/.config/hypr/bindings.lua und ergänze eine Zeile:

o.bind("SUPER + SHIFT + R", "SSH zum Server", "foot -e ssh mein-server")

Drei Angaben: die Tastenkombination, eine Beschreibung und der auszuführende Befehl. Die Beschreibung ist nicht bloß Dokumentation – sie taucht in der eingeblendeten Übersicht auf, die du mit SUPER + K aufrufst:

Eine vorhandene Belegung änderst du, indem du sie erst löst und dann neu vergibst:

hl.unbind("SUPER + SPACE")
o.bind("SUPER + SPACE", "Programmstarter", "mein-starter")

Und ein Kürzel, das du gar nicht willst, entfernst du mit hl.unbind("SUPER + SHIFT + B") ersatzlos.

Monitore: Der häufigste Stolperstein

Die Datei monitors.lua bestimmt Auflösung, Skalierung und Anordnung. Eine Zeile pro Bildschirm:

hl.monitor({ output = "DP-2", mode = "2560x1440@144", position = "0x0", scale = 1 })
hl.monitor({ output = "HDMI-A-1", mode = "1920x1080@60", position = "2560x0", scale = 1 })

Die Namen der Ausgänge liefert hyprctl monitors all. Derselbe Befehl zeigt unter availableModes auch, welche Auflösungen der Bildschirm überhaupt beherrscht.

Zwei Fallstricke, die viel Zeit kosten können:

Erstens meldet nicht jeder Monitor seine beste Auflösung als bevorzugt. In unserer Testinstallation gab der virtuelle Ausgang 1280x800 als bevorzugt an, obwohl er laut availableModes problemlos 1920x1080 konnte. Mit mode = "preferred" bleibt man dann unter den Möglichkeiten.

Zweitens hängt die Lesbarkeit an scale. Ein Wert von 2 auf einem 1280×800-Bildschirm bedeutet eine effektive Arbeitsfläche von 640×400 – alles wird riesig und es passt nichts mehr auf den Schirm. Auf gewöhnlichen Monitoren gehört dort 1 hin, auf 4K-Displays je nach Größe 1.5 oder 2.

Ein Hinweis zum Testen: Änderungen an der Monitorkonfiguration greifen nur, wenn die Sitzung gerade den Bildschirm besitzt. Wer sich per SSH oder von einer Textkonsole aus einloggt und dort etwas umstellt, wundert sich sonst, warum nichts passiert.

Optik: Abstände, Rahmen, Animationen

In looknfeel.lua sitzen die Werte, die den optischen Charakter ausmachen – vor allem die Abstände zwischen den Fenstern (gaps_in) und zum Bildschirmrand (gaps_out), die Rahmenbreite und die Eckenrundung.

Mein Rat: Fang klein an. Großzügige Abstände sehen auf Screenshots gut aus und kosten im Alltag Platz. Zwei bis fünf Pixel innen sind ein vernünftiger Ausgangspunkt.

Praktischer als jede Einstellung sind übrigens die Umschalter: SUPER + SHIFT + BACKSPACE blendet die Abstände vorübergehend ganz aus, SUPER + BACKSPACE schaltet die Fenstertransparenz um. Für einen Screenshot oder eine Präsentation reicht das meist völlig.

Themes: Das ganze System auf einmal umfärben

Hier liegt der größte sichtbare Hebel – und bei fertigen Distributionen ist es ein einziger Befehl. Omarchy bringt 22 Themes mit und färbt damit nicht nur den Fenstermanager, sondern auch Terminal, Editor, Browser, Statusleiste und das Hintergrundbild um.

Wie weitreichend das ist, zeigt derselbe Desktop in vier Themes. Identische Fenster, identischer Inhalt – nur die Farbwelt wechselt, und zwar überall gleichzeitig:

Auf der Kommandozeile geht es ebenso:

omarchy-theme-list
omarchy-theme-set "Gruvbox"

Wer Hyprland ohne solche Distribution nutzt, muss diese Ketten selbst knüpfen – jedes Programm bekommt seine eigene Farbdatei. Das ist die Fleißarbeit, die fertige Systeme abnehmen.

Änderungen übernehmen

Die meisten Anpassungen greifen nach:

hyprctl reload

Für schnelles Ausprobieren ohne Datei-Änderung gibt es hyprctl auch direkt. Achtung bei der Schreibweise: Systeme mit Lua-Konfiguration lehnen den früher üblichen Befehl hyprctl keyword ausdrücklich ab – dort heißt es stattdessen:

hyprctl eval 'hl.monitor({ output = "DP-2", mode = "1920x1080@60", scale = 1 })'

Wenn du dir die Konfiguration zerschossen hast: Hyprland startet trotzdem, meldet den Fehler aber. hyprctl configerrors nennt Datei und Zeile.

Was ich zuerst anpassen würde

Aus der Erfahrung mit dem Testsystem – in dieser Reihenfolge:

1. Monitore richtigstellen. Auflösung und Skalierung. Alles andere ist sinnlos, solange der Bildschirm nicht stimmt.
2. Tastaturlayout in input.lua. Deutsches Layout, Wiederholrate, Touchpad-Verhalten.
3. Zwei, drei eigene Tastenkürzel für die Programme, die du täglich startest.
4. Ein Theme aussuchen und dabei bleiben.
5. Abstände nachjustieren, wenn überhaupt.

Was ich nicht zuerst machen würde: Animationen feintunen. Das ist die zeitraubendste Baustelle mit dem geringsten Nutzen.

Fensterregeln: Jedes Programm dorthin, wo es hingehört

Die mit Abstand nützlichste Funktion, die neue Nutzer am längsten übersehen. Fensterregeln legen fest, wie sich ein bestimmtes Programm verhalten soll – unabhängig davon, wann und wo du es startest.

Typische Anwendungen:

• Der Taschenrechner soll schweben statt zu kacheln, weil er als halber Bildschirm albern aussieht.
• Das Musikprogramm soll immer auf Arbeitsfläche 5 landen.
• Bild-in-Bild-Fenster des Browsers sollen schweben und über allem bleiben.
• Dateidialoge sollen mittig erscheinen und eine feste Größe haben.

Den nötigen Bezeichner eines Fensters liefert hyprctl clients – dort stehen Klasse und Titel jedes offenen Fensters. Danach ist es eine Zeile in der Konfiguration.

Wer einmal drei, vier solcher Regeln geschrieben hat, merkt schnell, dass hier der eigentliche Komfortgewinn liegt: Das System ordnet sich selbst, ohne dass du nach jedem Programmstart etwas zurechtschiebst.

Tastatur und Touchpad: input.lua

Die Datei, die deutsche Nutzer als Erstes brauchen. Hier stellst du das Tastaturlayout ein, und zwar für den gesamten Desktop:

hl.input({ kb_layout = "de", kb_variant = "nodeadkeys", repeat_delay = 250, repeat_rate = 40 })

nodeadkeys ist eine Empfehlung für alle, die programmieren: Damit erscheinen Akzentzeichen sofort, statt auf den nächsten Tastendruck zu warten. Wer regelmäßig französische oder spanische Texte schreibt, lässt die Variante weg.

Die beiden Zahlen dahinter sind unterschätzt: repeat_delay ist die Verzögerung, bis eine gehaltene Taste zu wiederholen beginnt, repeat_rate die Geschwindigkeit danach. Die Vorgaben sind für Textverarbeitung gedacht; wer viel im Editor navigiert, wird mit kürzerer Verzögerung und höherer Rate deutlich glücklicher.

Für Notebooks kommen die Touchpad-Einstellungen hinzu – natürliches Scrollen, Tippen zum Klicken, Deaktivieren während des Schreibens. Letzteres ist die Einstellung, die verhindert, dass der Handballen beim Tippen den Cursor verschiebt.

Dotfiles: Die Konfiguration überleben lassen

Irgendwann hast du eine Einrichtung, die genau so ist, wie du sie willst. Spätestens dann gehört sie in ein Git-Repository – im Linux-Umfeld „Dotfiles“ genannt, weil die Konfigurationsverzeichnisse mit einem Punkt beginnen.

Der einfachste Anfang:

cd ~/.config/hypr
git init
git add .
git commit -m "Meine Hyprland-Konfiguration"

Damit hast du bereits das Wichtigste: eine Historie. Wenn nach einer Änderung etwas nicht mehr funktioniert, zeigt git diff in Sekunden, was du angefasst hast. Das ist im Alltag wertvoller als jedes Backup.

Im zweiten Schritt kommt das Repository auf einen Server – zu einem Anbieter oder in die eigene Nextcloud. Auf einem neuen Rechner klonst du es, und die Umgebung steht.

Eine Warnung: Konfigurationsverzeichnisse enthalten manchmal Zugangsdaten – Tokens, Schlüssel, Sitzungsdateien. Bevor du ein Repository veröffentlichst, sieh jede Datei durch. Bei Hyprland selbst ist das unproblematisch, bei anderen Programmen nicht immer.

Was Hyprland nicht steuert

Eine Quelle von Verwirrung: Nicht alles, was du auf dem Bildschirm siehst, gehört zu Hyprland. Die Statusleiste, der Programmstarter, die Benachrichtigungen, der Sperrbildschirm und das Hintergrundbild sind eigene Programme mit eigenen Konfigurationsdateien.

Wenn dich also die Uhr in der Leiste stört oder die Benachrichtigungen zu lange stehen bleiben, suchst du in ~/.config/hypr/ vergeblich. Bei Omarchy liegen diese Einstellungen unter ~/.config/omarchy/, bei selbstgebauten Umgebungen im jeweiligen Programmverzeichnis.

Die Faustregel: Alles, was mit Fenstern zu tun hat – Position, Größe, Rahmen, Arbeitsflächen, Tastenkürzel –, gehört Hyprland. Alles, was auf dem Desktop liegt, gehört jemand anderem.

Häufige Fragen

Muss ich Lua lernen?

Für die üblichen Anpassungen nicht. Du füllst vorgegebene Muster aus. Lua wird erst interessant, wenn du Wiederholungen zusammenfassen oder Bedingungen einbauen willst.

Meine Konfiguration aus einer Anleitung funktioniert nicht. Warum?

Mit hoher Wahrscheinlichkeit mischst du die Formate. Zeilen wie bind = SUPER, RETURN, exec, foot gehören zur alten Schreibweise, o.bind("SUPER + RETURN", ...) zur Lua-Form. Beides gleichzeitig geht nicht.

Wo finde ich alle möglichen Einstellungen?

Im offiziellen Hyprland-Wiki. Achte dabei auf die Version – das Projekt entwickelt sich schnell, und Optionen kommen und gehen.

Wie sichere ich meine Konfiguration?

Leg ~/.config/hypr/ in ein Git-Repository. Das ist der klassische Dotfiles-Ansatz: Auf einem neuen Rechner klonst du das Verzeichnis und hast deine Umgebung zurück.

Kann ich eigene Themes bauen?

Ja. Ein Theme ist im Kern eine Sammlung von Farbdefinitionen für die einzelnen Programme plus ein Hintergrundbild. Am einfachsten kopierst du ein vorhandenes und änderst die Farbwerte.

Was mache ich, wenn nach einer Änderung nichts mehr geht?

Mit STRG + ALT + F2 auf eine Textkonsole wechseln, dort anmelden und die Datei zurücksetzen. Deshalb lohnt es sich, vor größeren Umbauten eine Kopie anzulegen – oder eben Git zu nutzen.

Fazit

Die Umstellung auf Lua macht die Hyprland-Konfiguration mächtiger, aber auch uneinheitlicher: Ein großer Teil der Anleitungen im Netz beschreibt noch das alte Format. Wer das weiß, spart sich die frustrierende Suche nach dem eigenen Fehler.

Im Alltag reichen ohnehin vier Dateien und eine Handvoll Zeilen. Monitore, Eingabe, ein paar Tastenkürzel, ein Theme – der Rest ist Feinschliff, den man machen kann, aber nicht muss. Wer gerade erst anfängt, findet den Überblick in unserem Hyprland-Artikel, und die schnellste Art, ein fertiges System zu bekommen, steht in Omarchy installieren.