For NixOS users, a Nix package for Noctalia is available. You can also get the Git version, NixOS module and Home Manager module via flakes.
Warning To make Noctalia’s wifi, bluetooth, power-profile, and battery feature available, please ensure the following NixOS options are enabled:
networking.networkmanager.enablehardware.bluetooth.enableservices.power-profiles-daemon.enableorservices.tuned.enableservices.upower.enable
Nix flakes
To install Noctalia, you need to add a flake input and install the package.
Note The Noctalia flake requires nixpkgs unstable, since we depend on the latest Quickshell version.
Adding the flake input
Add the required inputs to your flake configuration:
# flake.nix
{
description = "NixOS configuration with Noctalia";
inputs = {
nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable";
noctalia = {
url = "github:noctalia-dev/noctalia/legacy-v4";
inputs.nixpkgs.follows = "nixpkgs";
};
};
outputs = inputs@{ self, nixpkgs, ... }: {
nixosConfigurations.awesomebox = nixpkgs.lib.nixosSystem {
specialArgs = { inherit inputs; };
modules = [
# ... other modules
./noctalia.nix
];
};
};
}
With the flake installed, we can access Noctalia packages and modules in our configuration.
Installing the package
If you don’t use Noctalia’s NixOS or home-manager modules, you need to manually install the default Noctalia package from the new noctalia input:
# noctalia.nix
{ pkgs, inputs, ... }:
{
# install package
environment.systemPackages = with pkgs; [
inputs.noctalia.packages.${pkgs.stdenv.hostPlatform.system}.default
# ... maybe other stuff
];
}
Rebuild with sudo nixos-rebuild switch --flake ..
Binary Cache
Pre-built binaries are available on Cachix, so you can skip compiling locally.
You can add the cache either to your flake, nixos configuration, or /etc/nix/nix.conf.
flake.nix
nixConfig = {
extra-substituters = [ "https://noctalia.cachix.org" ];
extra-trusted-public-keys = [ "noctalia.cachix.org-1:pCOR47nnMEo5thcxNDtzWpOxNFQsBRglJzxWPp3dkU4=" ];
};
#### configuration.nix
nix.settings = {
extra-substituters = [ "https://noctalia.cachix.org" ];
extra-trusted-public-keys = [ "noctalia.cachix.org-1:pCOR47nnMEo5thcxNDtzWpOxNFQsBRglJzxWPp3dkU4=" ];
};
#### nix.conf
extra-substituters = https://noctalia.cachix.org
extra-trusted-public-keys = noctalia.cachix.org-1:pCOR47nnMEo5thcxNDtzWpOxNFQsBRglJzxWPp3dkU4=
Config with home-manager
If you have home manager installed, you can configure your Noctalia shell in Nix.
Noctalia settings
To configure Noctalia settings, you can use the Noctalia home manager module:
# noctalia.nix
{ pkgs, inputs, ... }:
{
home-manager.users.drfoobar = {
# import the home manager module
imports = [
inputs.noctalia.homeModules.default
];
# configure options
programs.noctalia-shell = {
enable = true;
settings = {
# configure noctalia here
bar = {
density = "compact";
position = "right";
showCapsule = false;
widgets = {
left = [
{
id = "ControlCenter";
useDistroLogo = true;
}
{
id = "Network";
}
{
id = "Bluetooth";
}
];
center = [
{
hideUnoccupied = false;
id = "Workspace";
labelMode = "none";
}
];
right = [
{
alwaysShowPercentage = false;
id = "Battery";
warningThreshold = 30;
}
{
formatHorizontal = "HH:mm";
formatVertical = "HH mm";
id = "Clock";
useMonospacedFont = true;
usePrimaryColor = true;
}
];
};
};
colorSchemes.predefinedScheme = "Monochrome";
general = {
avatarImage = "/home/drfoobar/.face";
radiusRatio = 0.2;
};
location = {
monthBeforeDay = true;
name = "Marseille, France";
};
};
# this may also be a string or a path to a JSON file.
};
};
}
We don’t have extensive documentation of Noctalia’s configuration options; however, you can see an up-to-date list of configuration defaults.
Additionally, since ~/.config/noctalia/settings.json is now a read-only symlink, you can get the latest (or GUI-modified) settings via: Open Settings Panel -> General -> Copy Settings or by running noctalia-shell ipc call state all | jq .settings, then use them to update your Nix config for a permanent change.
Tip To see the diff between your current build and the latest (or GUI-modified) settings, run:
nix shell nixpkgs#json-diff -c bash -c "json-diff <(jq -S . ~/.config/noctalia/settings.json) <(noctalia-shell ipc call state all | jq -S .settings)"
Theme colors
To configure Noctalia settings, you can use the Noctalia home manager module. Be sure to set every Material 3 color, including hover-state values, when overriding the defaults:
# noctalia.nix
{ pkgs, inputs, ... }:
{
home-manager.users.drfoobar = {
# import the home manager module
imports = [
inputs.noctalia.homeModules.default
];
# configure options
programs.noctalia-shell = {
enable = true;
colors = {
# you must set ALL of these
mError = "#dddddd";
mOnError = "#111111";
mOnPrimary = "#111111";
mOnSecondary = "#111111";
mOnSurface = "#828282";
mOnSurfaceVariant = "#5d5d5d";
mOnTertiary = "#111111";
mOnHover = "#ffffff";
mOutline = "#3c3c3c";
mPrimary = "#aaaaaa";
mSecondary = "#a7a7a7";
mShadow = "#000000";
mSurface = "#111111";
mHover = "#1f1f1f";
mSurfaceVariant = "#191919";
mTertiary = "#cccccc";
};
# this may also be a string or a path to a JSON file.
};
};
}
User Templates
The user-templates option allows you to define custom templates. This is useful for theming other applications that are not supported by default.
It can be a string, a path, or an attribute set.
As a string:
# noctalia.nix
{ pkgs, inputs, ... }:
{
home-manager.users.drfoobar = {
# ...
programs.noctalia-shell = {
enable = true;
settings = {
templates = {
enableUserTemplates = true;
};
};
user-templates = ''
[config]
# General template settings
[templates.myapp]
input_path = "~/.config/noctalia/templates/myapp.css"
output_path = "~/.config/myapp/theme.css"
post_hook = "myapp --reload-theme"
'';
};
};
}
As a path:
# noctalia.nix
{ pkgs, inputs, ... }:
{
home-manager.users.drfoobar = {
# ...
programs.noctalia-shell = {
enable = true;
settings = {
templates = {
enableUserTemplates = true;
};
};
user-templates = ./path/to/user-templates.toml;
};
};
}
As an attribute set:
# noctalia.nix
{ pkgs, inputs, ... }:
{
home-manager.users.drfoobar = {
# ...
programs.noctalia-shell = {
enable = true;
settings = {
templates = {
enableUserTemplates = true;
};
};
user-templates = {
config = {
# General template settings
};
templates = {
myapp = {
input_path = "~/.config/noctalia/templates/myapp.css";
output_path = "~/.config/myapp/theme.css";
post_hook = "myapp --reload-theme";
};
};
};
};
};
}
Plugins
You can configure plugins in a declarative way. If an enabled plugin isn’t installed in the plugin directory, Noctalia will automatically install it when starts up.
# noctalia.nix
{ pkgs, inputs, ... }:
{
home-manager.users.drfoobar = {
# import the home manager module
imports = [
inputs.noctalia.homeModules.default
];
# configure options
programs.noctalia-shell = {
enable = true;
plugins = {
sources = [
{
enabled = true;
name = "Official Noctalia Plugins";
url = "https://github.com/noctalia-dev/legacy-v4-plugins";
}
];
states = {
catwalk = {
enabled = true;
sourceUrl = "https://github.com/noctalia-dev/legacy-v4-plugins";
};
};
version = 2;
};
# this may also be a string or a path to a JSON file.
pluginSettings = {
catwalk = {
minimumThreshold = 25;
hideBackground = true;
};
# this may also be a string or a path to a JSON file.
};
};
};
}
Wallpapers
Wallpapers are configured in ~/.cache/noctalia/wallpapers.json. You can set them declaratively:
# noctalia.nix
{ pkgs, inputs, ... }:
{
home-manager.users.drfoobar = {
# ... other config ...
home.file.".cache/noctalia/wallpapers.json" = {
text = builtins.toJSON {
defaultWallpaper = "/path/to/default/wallpaper.png";
wallpapers = {
"DP-1" = "/path/to/monitor/wallpaper.png";
};
};
};
};
}
Keybinds
Keybindings are configured in your compositor. You make IPC calls to Noctalia as explained in the keybinds section. The only difference is that you can call noctalia-shell instead of qs -c noctalia-shell.
To safely configure noctalia keybindings in the Niri flake, be sure to pass a list:
# niri.nix
{ pkgs, inputs, ... }:
{
# ...
home-manager.users.drfoobar =
{ config, ... }:
{
# ...
programs.niri = {
settings = {
# ...
binds = with config.lib.niri.actions; {
"Mod+Space".action.spawn = [
"noctalia-shell" "ipc" "call" "launcher" "toggle" # ✅
];
"Mod+P".action.spawn =
"noctalia-shell ipc call sessionMenu toggle"; # ❌
};
};
};
}
It may be convenient to define a utility function to allow you to use simple strings:
# niri.nix
{ pkgs, inputs, ... }:
let
noctalia = cmd: [
"noctalia-shell" "ipc" "call"
] ++ (pkgs.lib.splitString " " cmd);
in
{
# ...
home-manager.users.drfoobar =
{ config, lib, ... }:
{
# ...
programs = {
niri = {
# ...
settings = {
binds = with config.lib.niri.actions; {
# ...
"Mod+L".action.spawn = noctalia "lockScreen lock";
"XF86AudioLowerVolume".action.spawn = noctalia "volume decrease";
"XF86AudioRaiseVolume".action.spawn = noctalia "volume increase";
"XF86AudioMute".action.spawn = noctalia "volume muteOutput";
# etc
};
};
};
};
}
Running the shell
Systemd startup deprecation Systemd startup is deprecated for Noctalia.
This approach caused recurring technical issues, including delayed shell startup and unreliable IPC communication.
The old documentation is preserved for existing users here.
Please use the way shown below instead.
To run Noctalia using the flake, run:
noctalia-shell
With the Niri flake, you can then spawn Noctalia on startup like this:
# niri.nix
{ pkgs, inputs, ... }:
{
# ...
home-manager.users.drfoobar = {
# ...
programs.niri = {
package = niri;
settings = {
# ...
spawn-at-startup = [
{
command = [
"noctalia-shell"
];
}
];
};
};
};
}
Calendar events support
To add support for events in the calendar via evolution-data-server.
- Enable the evolution-data-server:
services.gnome.evolution-data-server.enable = true; - Override the Noctalia package:
(pkgs.noctalia-shell.override { calendarSupport = true; })or
(inputs.noctalia.packages.${pkgs.stdenv.hostPlatform.system}.default.override { calendarSupport = true; })
Configuration Defaults
There is no comprehensive documentation of all configuration options, but the default values are autogenerated and placed in a settings-default.json in the Noctalia repository. We retrieve a live Nixified version of these here for your convenience:
The complete settings reference, generated from nosDshell’s Assets/settings-default.json (the live descendant of Noctalia v4’s schema):
{
settingsVersion = 85;
bar = {
enabled = false;
barType = "simple";
floating = false;
position = "top";
monitors = [ ];
density = "default";
showOutline = false;
showCapsule = true;
capsuleOpacity = 1;
capsuleColorKey = "none";
widgetSpacing = 6;
contentPadding = 2;
fontScale = 1;
enableExclusionZoneInset = true;
backgroundOpacity = 0.93;
useSeparateOpacity = false;
marginVertical = 4;
marginHorizontal = 4;
frameThickness = 8;
frameRadius = 12;
outerCorners = true;
hideOnOverview = false;
displayMode = "always_visible";
autoHideDelay = 500;
autoShowDelay = 150;
showOnWorkspaceSwitch = true;
widgets = {
left = [ {
id = "Launcher";
} {
id = "ActiveWindow";
} ];
center = [ ];
right = [ {
id = "Tray";
} {
id = "MediaMini";
} {
id = "SystemMonitor";
} {
id = "Workspace";
} {
id = "NotificationHistory";
} {
id = "Battery";
} {
id = "Volume";
} {
id = "Brightness";
} {
id = "ControlCenter";
} {
id = "Clock";
} ];
};
mouseWheelAction = "none";
reverseScroll = false;
mouseWheelWrap = true;
middleClickAction = "none";
middleClickFollowMouse = false;
middleClickCommand = "";
rightClickAction = "controlCenter";
rightClickFollowMouse = true;
rightClickCommand = "";
screenOverrides = [ ];
};
general = {
avatarImage = "";
dimmerOpacity = 0.35;
showScreenCorners = false;
forceBlackScreenCorners = false;
scaleRatio = 1;
radiusRatio = 1;
iRadiusRatio = 1;
screenRadiusRatio = 1;
animationSpeed = 1;
animationDisabled = false;
lockScreenAnimations = false;
lockOnSuspend = true;
enableLockScreenMediaControls = false;
enableShadows = true;
enableBlurBehind = true;
shadowOffsetX = 0;
shadowOffsetY = 2;
language = "";
allowPanelsOnScreenWithoutBar = true;
enableLockScreenCountdown = true;
lockScreenCountdownDuration = 10000;
autoStartAuth = false;
allowPasswordWithFprintd = false;
passwordChars = false;
lockScreenMonitors = [ ];
lockScreenBlur = 1;
lockScreenTint = 0;
keybinds = {
keyUp = [ "Up" ];
keyDown = [ "Down" ];
keyLeft = [ "Left" ];
keyRight = [ "Right" ];
keyEnter = [ "Return" "Enter" ];
keyEscape = [ "Esc" ];
keyHome = [ "Home" ];
keyEnd = [ "End" ];
};
reverseScroll = false;
smoothScrollEnabled = true;
shadowStrength = 1.0;
};
ui = {
fontDefault = "";
fontFixed = "";
fontDefaultScale = 1;
fontFixedScale = 1;
tooltipsEnabled = true;
scrollbarAlwaysVisible = false;
boxBorderEnabled = false;
panelBackgroundOpacity = 0.65;
translucentWidgets = false;
panelsAttachedToBar = false;
settingsPanelMode = "controlCenter";
transientSurface = "auto";
transientOpacity = 1.0;
popupOpacity = 1.0;
borderEmphasis = 1.0;
rowHeightScale = 1.0;
accentOverride = "";
};
location = {
name = "";
weatherEnabled = true;
weatherShowEffects = true;
useFahrenheit = false;
use12hourFormat = false;
showWeekNumberInCalendar = false;
showCalendarEvents = true;
analogClockInCalendar = false;
firstDayOfWeek = -1;
hideWeatherTimezone = false;
hideWeatherCityName = false;
autoLocate = false;
};
calendar = {
cards = [ {
enabled = true;
id = "calendar-header-card";
} {
enabled = true;
id = "calendar-month-card";
} {
enabled = true;
id = "weather-card";
} ];
};
wallpaper = {
enabled = true;
overviewEnabled = false;
directory = "";
monitorDirectories = [ ];
enableMultiMonitorDirectories = false;
showHiddenFiles = false;
viewMode = "single";
setWallpaperOnAllMonitors = true;
linkLightAndDarkWallpapers = true;
fillMode = "crop";
fillColor = "#000000";
useSolidColor = false;
solidColor = "#1a1a2e";
automationEnabled = false;
wallpaperChangeMode = "random";
randomIntervalSec = 300;
transitionDuration = 1000;
transitionType = [ "fade" "disc" "stripes" "wipe" "pixelate" "honeycomb" ];
skipStartupTransition = false;
transitionEdgeSmoothness = 0.05;
panelPosition = "follow_bar";
useOriginalImages = false;
overviewBlur = 0.4;
overviewTint = 0.6;
useWallhaven = false;
wallhavenQuery = "";
wallhavenSorting = "relevance";
wallhavenOrder = "desc";
wallhavenCategories = "111";
wallhavenPurity = "100";
wallhavenRatios = "";
wallhavenApiKey = "";
wallhavenResolutionMode = "atleast";
wallhavenResolutionWidth = "";
wallhavenResolutionHeight = "";
sortOrder = "name";
favorites = [ ];
blurSigma = 0;
};
appLauncher = {
enableClipboardHistory = false;
autoPasteClipboard = false;
enableClipPreview = true;
clipboardWrapText = true;
enableClipboardSmartIcons = true;
enableClipboardChips = true;
clipboardWatchTextCommand = "wl-paste --type text --watch cliphist store";
clipboardWatchImageCommand = "wl-paste --type image --watch cliphist store";
mode = "fullscreen";
displayMode = "free";
iconRatio = 0.5;
pinnedApps = [ ];
sortByMostUsed = true;
terminalCommand = "alacritty -e";
customLaunchPrefixEnabled = false;
customLaunchPrefix = "";
viewMode = "grid";
showCategories = true;
iconMode = "tabler";
showIconBackground = false;
enableSettingsSearch = true;
enableWindowsSearch = true;
enableSessionSearch = true;
clearSearchOnClose = true;
ignoreMouseInput = false;
screenshotAnnotationTool = "";
density = "default";
};
controlCenter = {
diskPath = "/";
sysmonMetrics = [ "cpu" "temp" "mem" ];
quickPageOrder = [ "cards" "basic" "wifi" "bluetooth" "vpn" ];
shortcuts = {
left = [ {
id = "Network";
} {
id = "Bluetooth";
} {
id = "WallpaperSelector";
} {
id = "PerformanceMode";
} ];
right = [ {
id = "Notifications";
} {
id = "PowerProfile";
} {
id = "KeepAwake";
} {
id = "NightLight";
} ];
};
cards = [ {
enabled = true;
id = "profile-card";
} {
enabled = true;
id = "shortcuts-card";
} {
enabled = true;
id = "audio-card";
} {
enabled = true;
id = "brightness-card";
} {
enabled = true;
id = "weather-card";
} {
enabled = true;
id = "media-sysmon-card";
} ];
};
systemMonitor = {
cpuWarningThreshold = 80;
cpuCriticalThreshold = 90;
tempWarningThreshold = 80;
tempCriticalThreshold = 90;
gpuWarningThreshold = 80;
gpuCriticalThreshold = 90;
memWarningThreshold = 80;
memCriticalThreshold = 90;
swapWarningThreshold = 80;
swapCriticalThreshold = 90;
diskWarningThreshold = 80;
diskCriticalThreshold = 90;
diskAvailWarningThreshold = 20;
diskAvailCriticalThreshold = 10;
batteryWarningThreshold = 20;
batteryCriticalThreshold = 5;
enableDgpuMonitoring = false;
useCustomColors = false;
warningColor = "";
criticalColor = "";
externalMonitor = "resources || missioncenter || jdsystemmonitor || corestats || system-monitoring-center || gnome-system-monitor || plasma-systemmonitor || mate-system-monitor || ukui-system-monitor || deepin-system-monitor || pantheon-system-monitor";
};
performance = {
disableWallpaper = true;
disableDesktopWidgets = true;
};
debug = {
enabled = false;
modules = "";
logLevel = "info";
};
dock = {
enabled = true;
mode = "fashion";
iconSize = 36;
hideMode = "keep-showing";
plugins = [ {
id = "Tray";
} {
id = "NotificationHistory";
} {
id = "Network";
} {
id = "Volume";
} {
id = "Battery";
} {
id = "Clock";
} {
id = "SessionMenu";
} {
id = "plugin:usb-drive-manager";
} {
id = "Trash";
} ];
position = "bottom";
onlySameOutput = true;
monitors = [ ];
pinnedApps = [ ];
colorizeIcons = false;
launcherUseDistroLogo = false;
launcherIcon = "";
launcherIconColor = "none";
pinnedStatic = false;
groupApps = true;
groupContextMenuMode = "extended";
groupClickAction = "cycle";
deadOpacity = 0.6;
backgroundOpacity = 1.0;
pluginSpacing = 4;
fusedPlugins = false;
launcherIconSize = 0;
taskManagerCommand = "btop";
taskbarWidgets = {
left = [ {
id = "Launcher";
} {
id = "Taskbar";
} ];
center = [ ];
};
};
network = {
bluetoothRssiPollingEnabled = false;
bluetoothRssiPollIntervalMs = 60000;
networkPanelView = "wifi";
wifiDetailsViewMode = "grid";
ethernetDetailsViewMode = "grid";
bluetoothHideUnnamedDevices = false;
bluetoothAutoConnect = true;
};
sessionMenu = {
enableCountdown = true;
countdownDuration = 10000;
showKeybinds = true;
powerOptions = [ {
action = "shutdown";
enabled = true;
keybind = "1";
} {
action = "reboot";
enabled = true;
keybind = "2";
} {
action = "suspend";
enabled = true;
keybind = "3";
} {
action = "hibernate";
enabled = true;
keybind = "4";
} {
action = "lock";
enabled = true;
keybind = "5";
} {
action = "logout";
enabled = true;
keybind = "6";
} {
action = "rebootToUefi";
enabled = true;
keybind = "7";
} ];
};
notifications = {
enabled = true;
doNotDisturb = false;
enableMarkdown = false;
density = "default";
monitors = [ ];
location = "top_right";
overlayLayer = true;
backgroundOpacity = 1;
respectExpireTimeout = false;
lowUrgencyDuration = 3;
normalUrgencyDuration = 5;
criticalUrgencyDuration = 15;
maxVisible = 1;
clearDismissed = true;
saveToHistory = {
low = true;
normal = true;
critical = true;
};
sounds = {
enabled = false;
volume = 0.5;
separateSounds = false;
criticalSoundFile = "";
normalSoundFile = "";
lowSoundFile = "";
excludedApps = "discord,firefox,chrome,chromium,edge";
};
enableMediaToast = false;
enableKeyboardLayoutToast = true;
enableBatteryToast = true;
};
osd = {
enabled = true;
location = "bottom_center";
autoHideMs = 1000;
overlayLayer = true;
enabledTypes = [ 0 1 2 ];
monitors = [ ];
};
audio = {
volumeStep = 5;
volumeOverdrive = false;
spectrumFrameRate = 30;
visualizerType = "linear";
spectrumMirrored = true;
mprisBlacklist = [ ];
preferredPlayer = "";
volumeFeedback = false;
volumeFeedbackSoundFile = "";
};
brightness = {
brightnessStep = 5;
enforceMinimum = true;
enableDdcSupport = false;
backlightDeviceMappings = [ ];
};
colorSchemes = {
useWallpaperColors = false;
predefinedScheme = "Deepin";
darkMode = true;
schedulingMode = "off";
manualSunrise = "06:30";
manualSunset = "18:30";
generationMethod = "tonal-spot";
monitorForColors = "";
syncGsettings = true;
runDarkmanHooks = true;
};
templates = {
activeTemplates = [ ];
enableUserTheming = false;
};
nightLight = {
enabled = false;
forced = false;
autoSchedule = true;
nightTemp = "4000";
dayTemp = "6500";
manualSunrise = "06:30";
manualSunset = "18:30";
};
hooks = {
enabled = false;
wallpaperChange = "";
darkModeChange = "";
screenLock = "";
screenUnlock = "";
performanceModeEnabled = "";
performanceModeDisabled = "";
startup = "";
session = "";
colorGeneration = "";
};
plugins = {
autoUpdate = false;
notifyUpdates = true;
};
idle = {
enabled = false;
screenOffTimeout = 600;
lockTimeout = 660;
suspendTimeout = 1800;
fadeDuration = 5;
screenOffCommand = "";
lockCommand = "";
suspendCommand = "";
resumeScreenOffCommand = "";
resumeLockCommand = "";
resumeSuspendCommand = "";
customCommands = "[]";
};
desktopWidgets = {
enabled = false;
overviewEnabled = true;
gridSnap = false;
gridSnapScale = false;
monitorWidgets = [ ];
};
}