v5-compositor-settings-hyprland.md
Add the following settings to your Hyprland Lua configuration file (usually found at ~/.config/hypr/hyprland.lua).
Section titled “Autostart Noctalia”
Add this to your hyprland.start event hook:
hl.on("hyprland.start", function() hl.exec_cmd("noctalia")end)
Section titled “Compositor Settings”
Add the following to your existing hl.config({}) block. These settings are for general window appearance and functionality.
hl.config({ general = { gaps_in = 5, gaps_out = 10, },
decoration = { rounding = 20, rounding_power = 2,
shadow = { enabled = true, range = 4, render_power = 3, color = 0xee1a1a1a, },
blur = { enabled = true, size = 3, passes = 2, vibrancy = 0.1696, }, },})
Section titled “Persistent Workspaces”
For the best workspace indicator behavior, make your regular Hyprland workspaces persistent. This keeps empty workspaces visible in Noctalia instead of only showing workspaces that currently contain windows.
Update the monitor name and workspace list to match your setup. You can find more syntax and examples in the official Workspace Rules documentation.
hl.workspace_rule({ workspace = "1", monitor = "DP-1", persistent = true })hl.workspace_rule({ workspace = "2", monitor = "DP-1", persistent = true })hl.workspace_rule({ workspace = "3", monitor = "DP-1", persistent = true })hl.workspace_rule({ workspace = "4", monitor = "DP-1", persistent = true })hl.workspace_rule({ workspace = "5", monitor = "DP-1", persistent = true })
Add these binds to your hyprland.lua:
local ipc = "noctalia msg"
-- Core bindshl.bind(mainMod .. "+Space", hl.dsp.exec_cmd(ipc .. " panel-toggle launcher"))hl.bind(mainMod .. "+S", hl.dsp.exec_cmd(ipc .. " panel-toggle control-center"))hl.bind(mainMod .. "+comma", hl.dsp.exec_cmd(ipc .. " settings-toggle"))
-- Media keyshl.bind("XF86AudioRaiseVolume", hl.dsp.exec_cmd(ipc .. " volume-up"))hl.bind("XF86AudioLowerVolume", hl.dsp.exec_cmd(ipc .. " volume-down"))hl.bind("XF86AudioMute", hl.dsp.exec_cmd(ipc .. " volume-mute"))hl.bind("XF86MonBrightnessUp", hl.dsp.exec_cmd(ipc .. " brightness-up"))hl.bind("XF86MonBrightnessDown", hl.dsp.exec_cmd(ipc .. " brightness-down"))
-- Noctalia Settingshl.window_rule({ match = { class = "dev.noctalia.Noctalia" }, float = true, size = { 1080, 920 },})
Enable blur for Noctalia’s bar, panels, dock, and notifications. We also disable Hyprland’s built-in layer animations for Noctalia so they do not interfere with Noctalia’s own animations.
Blurred Noctalia surfaces
hl.layer_rule({ name = "noctalia", match = { namespace = "^noctalia-(bar-.+|notification|dock|panel|attached-panel|osd)$", }, no_anim = true, ignore_alpha = 0.5, blur = true, blur_popups = true,})