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)

  1. User settings – ~/.config/... (xfconf user files, ~/.config/luxos/*, dconf user database).
  2. LuxOS defaults – /etc/xdg/luxos (package luxos-desktop, luxos-shell).
  3. 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>.xml away, log in again – the /etc/xdg/luxos defaults 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-done or welcome-done to see Tour/Welcome again.
  • LuxOS flags: deleting a flag file in ~/.config/luxos turns 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.