Where configuration lives
LuxOS never overwrites the configuration files of other packages. Its desktop defaults live in a
separate XDG directory, user changes always win, and most LuxOS apps keep small state files in
~/.config/luxos.
Layers (highest priority first)
- User settings –
~/.config/...(xfconf user files,~/.config/luxos/*, dconf user database). - LuxOS defaults –
/etc/xdg/luxos(packageluxos-desktop,luxos-shell). - Upstream defaults –
/etc/xdg(Xfce and other packages).
/etc/profile.d/luxos.sh (package luxos-shell) prepends LuxOS directories:
XDG_CONFIG_DIRS=/etc/xdg/luxos:/etc/xdg– LuxOS defaults before upstream ones,XDG_DATA_DIRS=/var/lib/luxos/apps:/usr/share/luxos/xdg:…– short application names (generated by a package hook into/var/lib/luxos/apps) and hidden technical entries (/usr/share/luxos/xdg), plus/usr/lib/luxos/panel/share(top-bar plugins running inside the panel process),PATH=/usr/lib/luxos/override-bin:…– LuxOS replacements for some Xfce dialogs (e.g. desktop settings open Desktop & Dock).
/etc/xdg/luxos
| Path | Content |
|---|---|
xfce4/xfconf/xfce-perchannel-xml/*.xml |
default xfconf channels (see below) |
xfce4/panel/default.xml |
top bar layout |
autostart/ |
luxos-session, plank, blueman, print-applet |
gtk-3.0/settings.ini, gtk-4.0/settings.ini |
GTK defaults |
fastfetch/config.jsonc |
fastfetch layout |
xfconf channels
xfconf does not merge files – a channel file with higher priority replaces the whole channel.
Therefore, when the package is built, merge-xfconf.py deep-merges every LuxOS channel with the
Xfce default file (LuxOS values win; for keyboard shortcuts Xfce defaults are copied into custom).
Channels shipped by LuxOS: xsettings, xfwm4, xfce4-panel, xfce4-desktop, xfce4-session,
xfce4-power-manager, xfce4-screensaver, xfce4-notifyd, xfce4-terminal (only for systems that still have it),
xfce4-keyboard-shortcuts, keyboard-layout, displays, thunar.
Properties LuxOS tools read/write (examples):
| Channel / property | Used by |
|---|---|
xsettings /Net/ThemeName, /Net/IconThemeName |
light/dark appearance (luxos-appearance) |
xsettings /Xft/DPI |
text size (Displays) |
xfwm4 /general/theme, /general/use_compositing |
window theme, compositor (always re-enabled at login) |
xfce4-panel /panels/dark-mode, /panels/panel-1/background-rgba |
top bar appearance |
xfce4-panel /plugins/plugin-1/command-profile |
user menu opens LuxAI Account |
xfce4-desktop /backdrop/screen0/monitor*/workspace*/last-image, image-style |
wallpaper (Desktop & Dock) |
xfce4-notifyd /do-not-disturb, /theme |
Do Not Disturb, notification theme |
xfce4-keyboard-shortcuts |
Keyboard Shortcuts app |
keyboard-layout /Default/XkbDisable |
user session follows the system keyboard layout |
displays /Default |
display profile |
xfce4-power-manager /xfce4-power-manager/* |
Battery & Power (screen off, sleep, lid) |
xfce4-screensaver |
Screen Saver & Lock |
User changes are stored by xfconf in ~/.config/xfce4/xfconf/xfce-perchannel-xml/<channel>.xml.
Resetting a property (xfconf-query -c <channel> -p <property> -r) returns it to the LuxOS/system
default.
dconf / gsettings
/etc/dconf/profile/user (user-db:user, system-db:local) and /etc/dconf/db/local.d/10-luxos
contain defaults for the Plank Dock (net.launchpad.plank.dock.settings
/net/launchpad/plank/docks/dock1/: theme, bottom position, icon size 48, zoom 150 %,
hide-mode='window-dodge') and GTK4/libadwaita apps. Dock launchers for new users come from
/etc/skel/.config/plank/dock1/launchers/.
~/.config/luxos (per user)
| Path | Owner | Purpose |
|---|---|---|
initialized |
luxos-session | first-login setup done (user dirs, appearance) |
appearance |
luxos-appearance | current mode (light/dark) |
appearance.conf |
Desktop & Dock (luxos-settings) |
APPEARANCE_AUTO, bar/dock opacity etc. |
dock-autohide |
luxos-session / menubar | flag: Dock hides |
dock-zoom |
luxos-powersaver (older versions) | Dock zoom value, restored once and removed |
powersaver.saved |
luxos-powersaver | original values restored when Battery Saver turns off |
sleep-while-playing |
Battery & Power | flag: sleep even while media plays (option off) |
sleep-override |
luxos-hub | xfce4-power-manager values replaced while media plays |
datasaver |
luxos-datasaver | flag: Data Saver on |
powersaver |
luxos-powersaver | flag: Battery Saver on |
powersaver-auto |
Battery & Power | flag: automatic Battery Saver at 20 % |
brightness |
Control Center / luxos-displays | software brightness for monitors without backlight |
displays.json, displays-mode |
Displays / luxos-displays / Control Center | resolution, rotation, monitor layouts (layouts) and multi-monitor mode (modes) per set of monitors; displays-mode = last chosen mode for new sets |
shortcuts.json |
Keyboard Shortcuts | names of custom shortcuts |
screenshot.json |
Screenshot tool | save location, timer, pointer options |
camera.json |
Camera | camera settings |
scan.json |
Scanner (luxos-scan) |
scanner settings |
calculator |
Calculator | calculator state |
safe.json |
Safe | idle_minutes, lock_on_screen_lock |
shell.conf |
bash/lsh/zsh setup | LUXOS_BLESH=0, LUXOS_FASTFETCH=0 |
scrolling.conf |
Scrolling (luxos-scrolling) |
[scrolling] smooth_wheel, kinetic (scrolling.md) |
drivers-ignored |
Drivers notifier | hardware the user chose to ignore |
netcheck-added |
luxos-hub | top-bar network check plugin added |
calendar-clock-migrated |
Calendar | one-time migration flag |
tour-done, welcome-done |
Tour / Welcome | first-login windows already shown |
whats-new-seen |
What's New | last version whose news were shown |
Other per-user locations:
| Path | Purpose |
|---|---|
~/.config/luxai/account.json |
LuxAI account (secret token, 0600) – see LuxAI account |
~/.config/lux/lux.conf |
personal override of /etc/lux/lux.conf |
~/.config/luxdrop/ |
LuxDrop settings (settings.json) and data |
~/.local/share/luxos/calendar/events.ics |
Calendar events (other *.ics there are read-only) |
~/.config/gtk-3.0/gtk.css |
LuxOS keeps a managed block there for appearance; the rest is yours |
~/.config/gtk-4.0/gtk.css |
managed block with the window buttons of GTK 4/libadwaita apps; the rest is yours |
~/.config/gtk-3.0/bookmarks |
Files sidebar (Safe bookmark) |
~/.lshrc, ~/.lsh_history, ~/.config/starship.toml |
shell, see Shell |
~/.config/plank/dock1/launchers/ |
Dock items |
~/Sandbox |
folder shared with the sandbox (only with --shared) |
System-wide files
The whole system (packages, services, users, computer name, language, keyboard, Care, Guard,
firewall, kernel parameters) can also be described in one LSL file, /etc/luxos/system.lsl,
applied with lux system apply - see system-config.md.
| Path | Owner | Purpose |
|---|---|---|
/etc/lux/lux.conf |
lux-engine | package manager configuration (TOML: [general], [downloads], [security], [packages], [repo.NAME], [include]): repositories, signatures, hold, aur, flatpak, cache_keep – see package-management.md |
/etc/lux/conf.d/*.conf, /etc/lux/mirrorlist |
admin / lux-engine | extra repositories; Arch mirrors (one address per line, lux mirrors) |
/run/lux/engine.conf |
lux-config | generated config for the C engine tools – never edit (there is no /etc/pacman.conf) |
/etc/luxos/care.conf |
LuxOS Care | MODE=carefree (default if missing) or classic |
/etc/luxos/esp.conf |
installer / LuxOS Care | EFI system partition directory and kernel (ESP_DIR, KERNEL) |
/etc/luxos/templates.conf |
installer | app sets chosen at installation (TEMPLATES=…) |
/var/lib/luxos-care/ |
LuxOS Care | state.json, events.json, history.jsonl (readable, nothing secret) |
/etc/lsh/lshrc |
lsh | system lsh config (backup file) |
/etc/profile.d/luxos.sh |
luxos-shell | XDG/PATH environment |
/etc/X11/xorg.conf.d/00-keyboard.conf, /etc/vconsole.conf |
Keyboard Layouts (localectl) |
system keyboard layouts, also for the login screen |
/etc/X11/xorg.conf.d/30-luxos-touchpad.conf |
luxos-desktop | tap-to-click, two-finger right click, edge scrolling |
/etc/X11/xinit/xinitrc.d/50-luxos-firefox-xinput2.sh |
luxos-desktop | MOZ_USE_XINPUT2=1: Firefox touchpad scrolling with inertia (scrolling.md) |
/etc/lightdm/lightdm.conf.d/50-luxos.conf |
luxos-desktop | login manager |
/etc/systemd/zram-generator.conf |
luxos-tweaks | zram size/compression (backup file) |
/usr/lib/sysctl.d/99-luxos.conf, 60-luxos-safe.conf |
luxos-tweaks, luxos-safe | kernel tuning (override in /etc/sysctl.d/) |
/etc/makepkg.conf.d/luxos.conf, lux-engine.conf |
luxos-tweaks, lux-engine | AUR build settings, tool paths |
/usr/lib/luxos/services |
luxos-tweaks | services enabled by the installer |
/var/lib/luxos/sandbox/<user>, /etc/tmpfiles.d/luxos-sandbox-<user>.conf |
luxos-sandbox | sandbox root and its /dev/sandbox link |
/safe/.vaults/<user> |
luxos-safe | encrypted Safe data |
/usr/lib/luxos/python/ |
several | shared Python modules (luxai_account.py, luxos_i18n.py, …) |
/usr/share/luxos/i18n/ |
luxos-i18n | translations (cs.tsv, de.tsv, …) |
Files under /usr/lib belong to packages and are replaced on update; put local overrides in the
matching /etc directory instead (e.g. /etc/sysctl.d/, /etc/systemd/system/<unit>.d/).
When an update ships a new version of an /etc file you edited, LuxOS merges it automatically: your
values stay, new settings and comments are added (details in
lux-engine-and-repos.md). Only a version
that cannot be combined without a conflict waits as *.luxnew — review it with
sudo lux config-diff <file>.
Resetting to defaults
- One xfconf setting:
xfconf-query -c <channel> -p <property> -r. - A whole Xfce channel: log out, move
~/.config/xfce4/xfconf/xfce-perchannel-xml/<channel>.xmlaway, log in again – the/etc/xdg/luxosdefaults apply. - Keyboard shortcuts: Keyboard Shortcuts › Restore All Defaults… (or Restore Default per action).
- Dock:
dconf reset -f /net/launchpad/plank/docks/dock1/restores the LuxOS dconf defaults. - First-login windows: delete
~/.config/luxos/tour-doneorwelcome-doneto see Tour/Welcome again. - LuxOS flags: deleting a flag file in
~/.config/luxosturns the feature off (e.g.datasaver), but prefer the matching command (luxos-datasaver off) so the system state is updated too. - Sandbox:
luxos-sandbox reset. Safe: there is no reset that keeps the data.
Always back up a file before moving or deleting it, and never delete ~/.config/luxai/account.json to
"fix" sign-in – use luxos-account login.