Package management with lux
lux is the LuxOS package manager and the only supported way to install, update and remove
software from the command line. It manages packages from the LuxOS and Arch Linux repositories
directly through libalpm (used from Python via pyalpm), and also handles Flathub (Flatpak),
the community source (AUR, built and installed into your sandbox by default) and the LuxOS .lux
app format.
There is no pacman command and no /etc/pacman.conf in LuxOS. The configuration is
/etc/lux/lux.conf in its own format (see Configuration). The engine
behind lux is the lux-engine package (libalpm and tools taken from Arch Linux pacman) — see
lux-engine-and-repos.md.
- Program:
/usr/bin/lux(bash); transaction backend/usr/lib/lux/lux_alpm.py. .luxsupport:/usr/lib/lux/luxpkg.sh(see lux-packages.md).- Reference installed with the package:
/usr/share/doc/lux/lux.md.
Files
| Path | What it is |
|---|---|
/etc/lux/lux.conf |
configuration (TOML): repositories, signatures, held packages, lux settings |
/etc/lux/conf.d/*.conf |
more files in the same format (repositories added by packages or the admin) |
/etc/lux/lux.conf.old-format |
the original LuxOS 0.9 file after conversion (lux config migrate) |
/etc/lux/mirrorlist |
Arch Linux download mirrors, one address per line (lux mirrors) |
~/.config/lux/lux.conf |
per-user lux settings (only [packages] aur, review_pkgbuild, flatpak, cache_keep) |
/var/lib/lux/ |
package database (local/, sync/, lock db.lck); installed/ = .lux apps |
/var/cache/lux/pkg/ |
downloaded packages |
/var/log/lux.log |
transaction log (lux history) |
/etc/lux/keyring/ |
GnuPG keyring for package signatures (lux fix repairs it) |
/etc/lux/hooks/ |
admin hooks (*.hook, alpm-hooks format) |
/run/lux/engine.conf |
generated configuration of the C engine tools — never edit, it is rebuilt from lux.conf |
Commands
| Command (aliases) | What it does |
|---|---|
lux (no arguments) |
interactive store in the terminal (TUI, needs fzf) |
lux install <pkg...> (i, add) |
install from repositories → LuxOS .lux → Flathub → community (AUR, into the sandbox); also a local .lux or .pkg.tar.* file; installed packages are skipped |
lux remove <pkg...> (rm) |
remove with no longer needed dependencies; config files you changed stay as *.luxsave (-n/--nosave deletes them too) |
lux update (upgrade, up) |
refresh databases, signing keys first, then the whole system; then community (AUR) packages in the system, .lux apps, Flatpak (+ unused runtimes removed) |
lux search <term> (s) |
search repositories, the LuxOS .lux repo, Flathub and AUR (--installed: only installed); a word also matches descriptions, a pattern only names (any case): ^vim starts, vim$ ends, ^vim$ exact, *qt* contains, lib*-git (* any, ? one char, whole name), % = *; quote patterns: lux search '*qt*' |
lux info <pkg> (show) |
details (installed, else repository, .lux, AUR) |
lux list [--installed] (ls) |
installed packages (including .lux); lux list <pattern> filters |
lux check (check-updates) |
available updates from freshly downloaded lists (temporary copy, no root, nothing changes) |
lux list --upgradable |
available updates according to the last database refresh |
lux list --explicit / --aur / --orphans / --lux |
explicitly installed / not from a repository / unneeded / .lux apps |
lux reinstall <pkg...> |
same version again (repository, else cache) |
lux autoremove |
remove orphaned dependencies |
lux files <pkg> / lux owns <file> |
files of a package / which package owns a file |
lux clean |
clean the cache (keeps cache_keep versions, removes uninstalled packages), offers autoremove |
lux fix |
repair a locked database, unfinished downloads and the signing keys |
lux configs |
review new config files from updates (.luxnew, .luxsave; older .pacnew, .pacsave too): diff, use new, keep yours, edit |
lux config-diff <file> [--merge\|--keep\|--new] |
new config version that could not be merged automatically: combine (your values stay), keep yours or use new (yours → <file>.lux-old) |
lux config [check\|show\|edit\|engine\|migrate] |
check (errors and warnings), show or edit /etc/lux/lux.conf; engine prints the generated config of the engine tools; migrate converts the old format |
lux history [n] [pkg] |
recent package changes from /var/log/lux.log |
lux mirrors |
fastest mirrors (reflector) written to /etc/lux/mirrorlist |
lux drivers / lux doctor / lux pack <dir> |
drivers (drivers.md), health check, build a .lux |
lux system show\|init\|edit\|check\|diff\|apply |
the whole system (packages, services, users, ...) in one LSL file /etc/luxos/system.lsl, see system-config.md |
Options: -y/--yes (no questions — otherwise lux always asks; community updates in the system still ask), -n/--nosave (lux remove
also deletes changed config files, no *.luxsave), -v/--verbose (package lists,
script output, raw errors), --repo (only official repositories), --aur/--community (only the
community source), --system (community package into the system instead of the sandbox), -h, -V.
lux install firefox
lux install ./myapp-1.0-1-any.lux
lux install zoom # not in the repositories -> Flathub (us.zoom.Zoom)
lux install org.gimp.GIMP # Flatpak app ID
lux remove zoom # also removes Flatpak apps (+ runtimes nothing uses)
lux -y update
lux owns /usr/bin/fastfetch
lux history 50 linux-luxos
Arch habits are translated: typing pacman -Syu (or lux -Syu) prints the matching lux command
(lux update), pacman -S x → lux install x.
Configuration: /etc/lux/lux.conf
Since LuxOS 1.0 lux.conf is a TOML file: the tables [general], [downloads], [security],
[packages], [paths], one [repo.NAME] table per repository and [include], each with
key = value lines. Text goes in quotes ("auto"), switches are true/false, numbers have no
quotes, lists are ["a", "b"] (also over several lines, with comments). # starts a comment to
the end of the line. lux reads the file itself (Python's TOML parser). Edit as root (lux config edit opens it and checks it afterwards), then run
lux config check.
# LuxOS Package Manager
# Configuration: /etc/lux/lux.conf
[general]
architecture = "auto"
color = true
candy = true
verbose = true
# updates: "stable" (releases) | "staging" (test builds before a release - for testers)
channel = "stable"
[downloads]
parallel = 10
check_space = true
user = "alpm"
[security]
signatures = "required"
local_signatures = "optional"
protect = ["lux-engine", "glibc"]
[packages]
aur = true
review_pkgbuild = true
flatpak = true
cache_keep = 2
hold = ["linux-firmware"] # keep at the current version
# ── LuxOS repositories ────────────────────────
[repo.luxos]
server = "https://luxos.lux-ai.cz/repo/$repo/$arch"
# ── Arch Linux repositories ───────────────────
[repo.core]
mirrors = "/etc/lux/mirrorlist"
# ── Additional configuration ──────────────────
[include]
files = ["/etc/lux/conf.d/*.conf"]
[include] is a table because in TOML a key = value line belongs to the table above it (an
include = … under [repo.extra] would be a key of that repository; lux still uses it, with a
warning). A bare include = … works only at the top of the file.
Keys
channel in [general] is the update channel: "stable" (default, released versions) or
"staging" (test builds before a release, for testers). See
care-updates.md.
| Table | Key | Value (default) | Meaning |
|---|---|---|---|
[general] |
architecture |
text or list ("auto") |
package architecture |
color, candy, verbose |
true | false (true) |
colors, Pac-Man progress bar, detailed lists | |
syslog |
true | false (false) |
also log to the system journal | |
[downloads] |
parallel |
number ≥ 1 (10) |
files downloaded at once |
check_space |
true | false (true) |
free space check | |
user |
user | "none" ("alpm") |
unprivileged user that downloads | |
timeout |
true | false (true) |
false = no timeout for slow mirrors |
|
sandbox |
true | false (true) |
restrict the download process | |
[security] |
signatures |
"required" | "optional" ("required") |
package/database signature checks; "never" only for a local file:// repo |
local_signatures |
"required" | "optional" | "never" ("optional") |
packages installed from a file (AUR builds) | |
protect |
list of packages (["lux-engine", "glibc"]) |
lux remove warns and never removes them with -y |
|
[packages] |
aur |
true | false (true) |
AUR packages (built on this computer) |
review_pkgbuild |
true | false (true) |
offer to read the build script before an AUR build | |
flatpak |
true | false (true) |
lux update also updates Flatpak apps |
|
cache_keep |
number (2) |
versions per package lux clean keeps |
|
hold |
list of packages | held packages: lux update skips them (pacman's IgnorePkg) |
|
ignore_group |
list of groups | the same for package groups | |
no_upgrade |
list of paths without leading / |
files updates never overwrite (new version saved as .luxnew) |
|
no_extract |
list of path patterns | files never extracted (e.g. usr/share/doc/*) |
|
[paths] |
cache, hooks |
absolute path or list | other cache / hook directories |
database, log, keyring |
absolute path | other database, log, keyring | |
[include] |
files |
list of paths or patterns (["/etc/lux/conf.d/*.conf"]) |
more files (relative = to this file), read after the whole file |
Lists from all files add up (hold in conf.d adds packages); other values read later win.
Repositories
One [repo.NAME] table per repository; table order is search order (first match wins; repositories
from [include] come after those of the file). Names with a dot or + need quotes: [repo."my.repo"].
| Key | Value | Meaning |
|---|---|---|
server |
"https://…", "http://…", "ftp://…", "file://…" or a list |
$repo and $arch are filled in |
mirrors |
path to a mirror list, or a list | addresses from the file (e.g. "/etc/lux/mirrorlist") |
signatures |
"required" | "optional" | "never" |
overrides the global setting ("never" only for file://) |
usage |
["sync", "search", "install", "upgrade"] or "all" |
what the repository is used for (default all) |
Mirror list: /etc/lux/mirrorlist
One address per line, best first, # comments. The default is the worldwide mirror
geo.mirror.pkgbuild.com (picks the nearest) plus a few reliable HTTPS mirrors. lux mirrors
replaces it with the fastest mirrors; reflector.timer refreshes it weekly. Server = … lines from
other tools are accepted when reading, but lux writes plain addresses.
Examples
- Add a repository — create
/etc/lux/conf.d/myrepo.conf, thenlux update:toml [repo.myrepo] server = "https://example.org/$repo/$arch"Import its signing key withsudo /usr/lib/lux/alpm/bin/lux-engine-key --recv-keys IDand--lsign-key ID.multilib(Steam):sudo /usr/lib/lux/lux-config enable-repo multilib. - Hold a package:
hold = ["linux-firmware"]in[packages](more names in the list). - Change mirrors:
lux mirrors, or edit/etc/lux/mirrorlist(one address per line). - Disable AUR:
aur = falsein[packages](for one user in~/.config/lux/lux.conf).
Errors and warnings
Wrong syntax and values are errors with the file and line:
lux: error in the configuration: /etc/lux/lux.conf:11: 'parallel' in [downloads] must be a whole number of at least 1 (without quotes), not "10"
lux: the package manager keeps using the last working configuration until this is fixed
✗ lux will not run until the configuration is fixed (/etc/lux/lux.conf). Check it with: lux config check
With a broken config lux, LuxOS Store and LuxOS Care install and update nothing until it is fixed;
hooks and makepkg keep the last working generated config. Other messages: must be true or
false, not "on", text values need quotes, the old 'key value' format, has no 'server' or
'mirrors' line, mirror list … does not exist, is already defined at FILE:LINE.
Unknown keys and tables are not errors: lux config check prints a warning with a suggestion and
the key is ignored:
lux: warning: /etc/lux/lux.conf:7: unknown key 'parallel' in [general] (it belongs to [downloads]) - ignored
Old format (LuxOS 0.9)
The LuxOS 0.9 format (key value lines, repo NAME blocks) is still read; lux config check
reports it and sudo lux config migrate converts it (same values, comments kept, original kept as
lux.conf.old-format; the lux-engine update does it once automatically). Key mapping and details:
lux-engine-and-repos.md.
How it works and migration from pacman
lux reads lux.conf, included files and mirror lists directly and sets up libalpm from the result
(other tools: lux_config.load(), in a shell /usr/lib/lux/lux-config json). Only the unmodified C
tools from Arch (lux-engine, lux-engine-key, makepkg) get a generated /run/lux/engine.conf
(see lux-engine-and-repos.md). Updating LuxOS 0.9.5 or older moves the
pacman data and converts /etc/pacman.conf ([multilib], IgnorePkg → hold, …) into lux.conf
(details).
Config files kept by updates are named after lux: *.luxnew (new version of a file you changed)
and *.luxsave (your changed file of a removed package). LuxOS 1.0 renames older *.pacnew,
*.pacsave and *.pacorig files in /etc once when lux-engine is updated (an existing
.luxnew/.luxsave is never overwritten; renamed files are listed in /var/log/lux.log).
lux configs, lux doctor and LuxOS Care still recognise the old names.
Edited config files get new versions merged automatically, see lux-engine-and-repos.md.
Administrator rights
Run lux as a normal user; it asks for root itself (sudo in a terminal, pkexec in a graphical
session). Community (AUR) packages are built as a regular user — never sudo lux install <aur-package>.
Environment: LUX_BACKEND=engine (force the lux-engine fallback), NO_COLOR, LUX_LOCK_WAIT
(seconds to wait for another package manager, default 300).
Flathub and the community source (AUR)
Order of sources for lux install <name>: LuxOS and Arch Linux repositories → LuxOS .lux apps →
Flathub → community (AUR). The first source that has the name wins.
Flathub (flatpak on):
- The name is looked up with the Flathub API (works before flatpak is installed): an app ID
(us.zoom.Zoom), an exact app name or the last part of the ID (zoom). Several matches → a
numbered choice (none with -y).
- lux offers to install flatpak, adds the flathub remote if missing and shows the download and
disk size, including the shared runtime (for example org.freedesktop.Platform, 0.5–1 GB)
when it is not installed yet. Runtimes are shared by all Flatpak apps.
- lux remove <id or name> removes the app and then runs flatpak uninstall --unused (runtimes
no app needs); lux update does the same after flatpak update. App data in ~/.var/app stays.
- A new app is in Launchpad and the app menu right away, for every user, without logging out —
also when it comes from the Store or a plain flatpak install. luxos-flatpak-apps.path
(luxos-desktop) watches /var/lib/flatpak/exports/share/applications and luxos-apps-sync links
the apps' .desktop files and the hicolor icons into /var/lib/luxos/apps, which every session
has in XDG_DATA_DIRS; removed apps lose their link. lux waits (at most 3 s) until the link is
there. The same app in both folders is shown once.
Community (AUR) — build scripts written by other users, not checked by LuxOS. Every build script is checked before building (fixed rules + two LuxAI models), the default target is your sandbox and LuxAI never installs community packages. Details, the measured detection rate and the install rules: community-aur.md.
lux update in detail
- Waits up to 5 minutes for another package manager (LuxOS Care, Store); a stale lock with nothing
running is removed (
Removed a stale database lock left by an interrupted update.). - Refreshes databases, updates
archlinux-keyring/luxos-keyringfirst, then the full system. - Community (AUR) packages in the system,
.luxapps, Flatpak apps (then unused Flatpak runtimes are removed); new versions of edited config files are merged automatically (only conflicts are listed, withsudo lux config-diff <file>), and it warns when a restart is needed.
Automatic background updates are done by LuxOS Care — see care-updates.md.
lux fix, doctor, clean
lux fix(as root): checks/var/lib/lux/db.lck— if a package manager runs (lux-engine,lux_alpm.py,makepkg, …) it saysAnother package manager is running (…), otherwise offers to remove the stale lock; deletes unfinished downloads; initializes/populates the keyring (lux-engine-key --init/--populate); warns about an unsynchronized clock; reinstalls the keyrings. Never deletedb.lckby hand while an update runs.lux doctor: failed services,.luxnewfiles, disk usage, orphans, available updates (checked into a temporary database copy), configuration errors, old package manager files waiting for cleanup, engine version vs. Arch, replaced kernel, journal errors.lux clean: own cache cleaner (no pacman-contrib): keepscache_keepnewest versions of installed packages, removes cached uninstalled packages, then offersautoremove.
Interactive terminal store (TUI)
lux without arguments opens an fzf store (LuxOS apps first, ● = installed). Keys: Enter install,
Ctrl-R remove, Ctrl-U update, Tab select more, Alt-L LuxOS apps, Alt-I installed, Alt-A all, Esc quit.
Machine mode (for apps)
LuxOS Store, LuxOS Care and the Drivers app call /usr/lib/lux/lux_alpm.py --machine -y COMMAND
(@@PLAN, @@PHASE, @@PROGRESS, @@ERROR <kind> <sentence>, @@DONE <code> …). Error kinds:
locked, network, keyring, disk, conflict, pkgconflict, deps, corrupt, notfound,
notinstalled, permission, confirm, cancelled, config, unknown. Exit codes: 0 ok,
1 error, 2 usage, 3 pyalpm unusable (fall back to lux-engine), 130 interrupted. Also
check-updates (0 updates, 2 none), clean, list --sync, migrate.
Error messages and what to do
| Message (kind) | Fix |
|---|---|
The package database is locked … (locked) |
wait for the other update, otherwise lux fix |
A package signature could not be verified … (keyring) |
lux fix; check the clock |
Some packages could not be downloaded … (network) |
check internet; lux mirrors |
Not enough free disk space … (disk) |
lux clean |
file conflict (conflict) |
lux owns <file> to find the owner |
Dependencies can not be satisfied (deps) |
usually a partial update; lux update first |
configuration has an error (config) |
lux config check, fix the reported line |
Package 'X' not found (notfound) |
lux search X |
The package X was damaged again after a new download (corrupt) |
lux already deleted the damaged file from /var/cache/lux/pkg and downloaded it once more; if it is damaged again, the server is probably being updated – try later |
The full command reference is also in the manual page: man lux.