omarchy

Source excerpt starting at line 1.

1# Hyprland Configuration2 3Read this before changing keybindings, monitors, window rules, or any other4Hyprland (window manager) configuration.5 6Omarchy configures Hyprland in Lua. User files are loaded after Omarchy's7defaults, so overrides go here:8 9```10~/.config/hypr/11├── hyprland.lua       # Main config (loads Omarchy defaults, then user files)12├── bindings.lua       # Keybindings13├── monitors.lua       # Display configuration14├── input.lua          # Keyboard/mouse settings15├── looknfeel.lua      # Appearance (gaps, borders, animations)16├── autostart.lua      # Startup applications17├── hyprsunset.conf    # Night light / blue light filter18└── xdph.conf          # Screen sharing / desktop portal19```20 21**Key behaviors (the `.lua` files):**22- Hyprland auto-reloads on config save (no restart needed for most changes)23- Use `hyprctl reload` to force reload24- After ANY Hyprland Lua config change, validate with `hyprctl reload` followed by `hyprctl configerrors`25- If `hyprctl configerrors` reports errors, address them and rerun validation until clean or until a real blocker is identified26- Use `omarchy refresh hyprland` to reset the Lua config files to defaults27 28The two `.conf` files are read by separate processes, so `hyprctl` neither29applies nor validates them:30- `hyprsunset.conf` (night light): apply changes with `omarchy restart hyprsunset`; reset with `omarchy refresh hyprsunset`31- `xdph.conf` (screen-sharing portal): applies when the portal restarts, e.g. on next login32 33## Keybindings34 35Edit `~/.config/hypr/bindings.lua`. Format:36```lua37o.bind("SUPER + SHIFT + R", "SSH", "alacritty -e ssh your-server")38o.bind("SUPER + B", "Browser", { launch = "chromium" })  -- launch wraps with uwsm-app39```40 41View current bindings: `omarchy menu keybindings --print`42 43**IMPORTANT: When re-binding an existing key:**44 451. First check existing bindings: `omarchy menu keybindings --print`462. If the key is already bound, use `o.rebind(...)` to remove the existing binding and add its replacement. It takes the same arguments as `o.bind(...)`.473. Inform the user what the key was previously bound to48 49Example - rebinding SUPER+F (which is bound to fullscreen by default):50```lua51-- Replace SUPER+F (was: fullscreen) with the file manager.52o.rebind("SUPER + F", "File manager", { launch = "nautilus" })53```54 55Tell the user which action was replaced. Use `hl.unbind(...)` to remove a binding without replacing it.56 57## Display/Monitors58 59Edit `~/.config/hypr/monitors.lua`. Format:60```lua61hl.monitor({ output = "eDP-1", mode = "1920x1080@60", position = "0x0", scale = 1 })62hl.monitor({ output = "HDMI-A-1", mode = "2560x1440@144", position = "1920x0", scale = 1 })63```64 65List monitors and supported modes: `hyprctl monitors all`66 67## Window Rules68 69**CRITICAL: Hyprland window rules syntax changes frequently between versions.**70 71Before writing ANY window rules, you MUST fetch the current documentation from the official Hyprland wiki:72- https://wiki.hypr.land/Configuring/Basics/Window-Rules/73 74DO NOT rely on cached or memorized window rule syntax. The format has changed multiple times and using outdated syntax will cause errors or unexpected behavior.75 76Window rules go in `~/.config/hypr/hyprland.lua` or a required Lua module. Prefer Omarchy's `o.window(match, rules)` helper — see examples in `$OMARCHY_PATH/default/hypr/windows.lua`.77