The interface is branded Noctalia Store. Existing command names, plugin IDs, NixOS options and data paths remain unchanged for compatibility.
A native Noctalia Shell v5 software browser for Nix, Flatpak and
Pacman. Search every configured source at once, compare where an application is available, and
install, update or remove it with the package manager you choose. Opens with Super+P.
| Confirm | Result |
|---|---|
![]() |
![]() |
Screenshots from the earlier branding: the real panel in Noctalia 5.0.1 with live Nix and Flathub data. The install shown was performed for real (per-user Flatpak) and then removed.
- Automatic source detection when the panel opens; each source is a real backend, not a label.
- Source filter: All · Nix · Flatpak · Pacman (
Ctrl+1–Ctrl+4). Unavailable sources are disabled with the reason in their tooltip and in the status line. - Asynchronous, debounced search: each source is queried by its own process; stale replies are discarded; slow sources never block the others. Empty search shows a featured list.
- Results with icon, name, version, summary, source badge, installed/update state and an explicit button: Install with Nix, Install with Flatpak, Install with Pacman.
- Details pane: publisher/maintainers, license (unfree flagged), website, package id, origin (remote and user/system installation, or repository) and "Also available from" showing the same application in the other sources with their versions and their own buttons.
- Views: Discover, Installed, Updates, Activity (history).
- Transactions: confirmation card for every change (destructive styling for removals),
progress bar, live log (
Ctrl+L), result verification, notifications. One transaction at a time; it keeps running if the panel is closed. - Theme-aware (uses Noctalia palette roles; follows dark/light), keyboard navigation
(
↑/↓,Enteracts on the selection,Ctrl+Enterconfirms,Ctrl+Fsearch,Esccloses).
| Nix (system mode) | Nix (profile mode) | Flatpak | Pacman | |
|---|---|---|---|---|
| Platform | NixOS with this module | Any Linux with Nix | Any Linux with Flatpak | Arch Linux and derivatives |
| Scope | Whole system, declarative | Current user | User or system installation | Whole system |
| What install does | Adds the attribute to a dedicated JSON list, rebuilds and activates NixOS | nix profile add |
flatpak install --user/--system |
pacman -S --needed |
| Privileges | Administrator (PolicyKit, fixed helper) | None | None for user; system installs authorised by Flatpak's own PolicyKit helper | Administrator (pkexec pacman) |
| Rollback | Previous NixOS generation; failed builds change nothing | nix profile rollback |
— | — |
| Updates | Whole system: refresh nixpkgs (channel or flake lock) and rebuild | nix profile upgrade (outside the panel) |
Per application, plus metadata refresh | Full pacman -Syu only |
| Sandboxed apps | No | No | Yes | No |
Pacman on NixOS is always disabled: pacman would write outside the Nix store and fight the declarative system. The panel explains this instead of pretending.
- Searches the same nixpkgs revision the system was built from (
pkgs.path, written by the module), or in profile mode thenixpkgsfromNIX_PATH/the flake registry. A one-time index (~24 000 top-level packages, about 10–60 s) is built by a background job and cached in~/.cache/noctalia-software-installer/, keyed by the nixpkgs store path. Nested package sets (for examplepython3Packages.*) are not indexed; they can still be installed by attribute path from the command line backend. - System mode edits only
nix.managedPackagesPath, a JSON array of attribute paths that the module adds toenvironment.systemPackages. Packages that are part of your configuration elsewhere are marked In system config and cannot be removed here. The root helper: validates the name, checks the attribute exists in nixpkgs, writes a recovery journal, edits the list, builds the complete system, registers and activates the generation, and restores the list (and the previous generation, if activation failed) on any error. An interrupted run is recovered from the journal on the next run. A success is reported only if/run/current-systemis the newly built system. - Profile mode installs from the same nixpkgs it searches and only removes packages it
installed itself (tracked in
~/.local/state/noctalia-software-installer/nix-profile.json).
- Detects remotes of both installations (
flatpak remotes). Search uses each remote's local appstream catalogue (the data behindflatpak search, cached as JSON per remote), so results show the publisher, license, version, homepage and the remote's own icons. User and system results for the same remote are separate rows (flathub (user) / flathub (system)). - Installed state per installation, update check (
flatpak remote-ls --updates, network), install, uninstall, update, metadata refresh (Updates view). - No remote configured → the panel offers Add Flathub… (per-user, after confirmation). Only the Flathub preset can be added from the UI.
- Enabled only when
pacmanand/etc/pacman.confexist, synchronized repositories are configured, and the host is not NixOS. - Search (
pacman -Ss, regex characters escaped), details (pacman -Si), installed state, pending upgrades from the last sync (pacman -Qu). - Install
pacman -S --needed --noconfirm -- repo/name; removepacman -R --noconfirm -- name(dependants make pacman fail and the error is shown); Full system upgradepacman -Syu. Databases are never refreshed without upgrading (no-Sypartial upgrades). A held/var/lib/pacman/db.lckblocks new transactions. - Commands run through
pkexecwith fixed argument lists.
- Noctalia v5, plugin API 24+ (tested on 5.0.1).
- Python 3 standard library (supplied by the Nix package).
- Optional: Nix, Flatpak, Pacman — whichever you want to use.
- For system-mode Nix and Pacman: PolicyKit with an authentication agent and an active local session.
{
inputs.noctalia-software-installer.url = "github:SwashX-dev/Noctalia-Store";
inputs.noctalia-software-installer.inputs.nixpkgs.follows = "nixpkgs";
outputs = { nixpkgs, noctalia-software-installer, ... }: {
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
./configuration.nix
noctalia-software-installer.nixosModules.default
{
programs.noctalia-software-installer = {
enable = true;
nix.managedPackagesFile = ./managed-packages.json; # read at evaluation
nix.managedPackagesPath = "/etc/nixos/managed-packages.json"; # edited by the helper
nix.rebuild.method = "flake";
nix.rebuild.flake = "/etc/nixos";
nix.rebuild.host = "myhost";
};
services.flatpak.enable = true; # optional
}
];
};
};
}Create the list once (echo '[]' | sudo tee /etc/nixos/managed-packages.json) and track it in
git (git add managed-packages.json), otherwise flakes cannot see it. The flake directory must be
root-owned (as /etc/nixos is); the helper refuses files other users can write.
{
imports = [ ./vendor/noctalia-software-installer/nix/module.nix ]; # a root-owned copy
programs.noctalia-software-installer = {
enable = true;
nix.managedPackagesFile = /etc/nixos/managed-packages.json;
nix.managedPackagesPath = "/etc/nixos/managed-packages.json";
# nix.rebuild.method = "channels"; (default; uses /etc/nixos/configuration.nix)
};
}echo '[]' | sudo tee /etc/nixos/managed-packages.json
sudo nixos-rebuild build && sudo nixos-rebuild switchWithout nix.managedPackagesFile the module installs the panel with Nix in profile mode only.
- installs the package, links
share/noctalia-software-installer; - adds the packages listed in the managed file to
environment.systemPackages; - writes
/etc/noctalia-software-installer/config.json(nixpkgs path, managed list path, list of protected base packages, helper path) andhelper.json(rebuild method); - enables PolicyKit and installs one action,
noctalia.software.nixos-transaction(auth_adminfor the active session, denied otherwise), bound to the fixed helper executable; - writes
/etc/noctalia-software-installer/niri-binds.kdl.
nix profile add github:SwashX-dev/Noctalia-Store
noctalia-software-setup applyFlatpak and (on Arch) Pacman work with the host's own tools; Nix works in profile mode.
noctalia-software-setup check
noctalia-software-setup applyapply backs up your Niri config, refuses to override an existing Super+P binding, validates
with niri validate, adds include optional=true "<binding file>", and registers and enables the
plugin local/software-installer via Noctalia's IPC. If Super+P already opens another software
center (for example the original rain-software-menu), replace it deliberately:
noctalia-software-setup apply --replace Mod+P # comments the old line out; `undo` restores itThe binding:
Mod+P hotkey-overlay-title="Noctalia Store" { spawn "noctalia" "msg" "panel-toggle" "local/software-installer:browser"; }Bar button: widget type local/software-installer:software-button.
| Option | Default | |
|---|---|---|
programs.noctalia-software-installer.enable |
false |
|
….package |
this repository | |
….keybinding |
"Mod+P" |
|
….installNiriBindings |
true |
|
….nix.declarative |
true |
Use system mode when a managed file is configured |
….nix.managedPackagesFile |
null |
Path read at evaluation time |
….nix.managedPackagesPath |
null |
Absolute on-disk path the helper edits (required with the file) |
….nix.rebuild.method |
"channels" |
or "flake" |
….nix.rebuild.configuration |
"/etc/nixos/configuration.nix" |
channels |
….nix.rebuild.flake / .host |
"/etc/nixos" / hostname |
flake |
….nix.allowSystemUpdate |
true |
Allow Update NixOS system |
The panel talks to noctalia-software, which can also be used directly (JSON output):
noctalia-software sources
noctalia-software search --source flatpak --query firefox
noctalia-software installed --source nix
noctalia-software updates --source flatpak
noctalia-software start --source flatpak --op install --id user/flathub/org.mozilla.firefox --confirmed
noctalia-software status # progress and log of the current/last transaction
noctalia-software historyIdentifiers: Nix attr.path; Flatpak user|system/<remote>/<app-id>; Pacman <repo>/<name>.
All are validated against strict grammars and passed as single arguments; no shell is involved.
- Nix shows "indexing" — the first index takes a while; it is a background job. If it failed,
the error is shown; delete
~/.local/state/noctalia-software-installer/nix-index-error.jsonto retry. - Flatpak: "No downloaded metadata" — use Refresh for that remote in the Updates view
(
flatpak update --appstream). - System install: "Authentication was cancelled" — nothing changed. "must be root-owned" — fix ownership/permissions of the managed file and its directory.
- Build failed — open the log (
Ctrl+L); the package list was restored and the running system was not changed. - "Another package operation is running" — wait for it (see Activity /
noctalia-software status). - Logs:
~/.local/state/noctalia-software-installer/operation.log; helper history/var/lib/noctalia-software-installer/history.jsonl.
Update the flake input or your checkout and rebuild (NixOS), or nix profile upgrade noctalia-software-installer.
noctalia-software-setup undorestores the backed-up Niri config (including a replacedSuper+Pline) and disables the plugin;removeonly drops the managed include.- Remove the module and rebuild. Packages installed declaratively stay in
managed-packages.json; move them into your own configuration first if you want to keep them. sudo nixos-rebuild switch --rollback(or an older boot entry) returns to any previous generation; every system-mode install/remove creates one.- Per-user data:
~/.local/state/noctalia-software-installer,~/.cache/noctalia-software-installer.
- Nix search covers top-level nixpkgs attributes only; per-package update notices are not shown for Nix (NixOS updates the whole system).
- Declarative installs require a root-owned managed file (a flake in a user-owned home directory is not supported by the helper).
- The Flatpak update check needs network access to the remotes.
- Pacman support was tested against a real
pacman7.0 binary and a generated local repository (search, details, safe command construction); installing/removing on a real Arch system was not performed during development. - The graphical PolicyKit prompt is provided by your session's agent; nothing is installed for it.
nix flake check -L
nix build .#default -L
PYTHONPATH=backend:tests python3 -m unittest discover -s tests -v| Test | Kind |
|---|---|
test_flatpak.py: remote detection, appstream parsing, search, user/system state, updates, unavailable repository, exact commands, invalid ids, remote setup, verification, caching |
Mocked flatpak CLI, generated appstream |
test_nix.py: modes, search/ranking, protected packages, background indexing, index error, command construction, unfree handling, profile tracking, verification |
Mocked |
test_pacman.py: NixOS refusal, missing pacman, repositories, search parsing, regex escaping, errors, safe commands, no partial upgrades, lock handling |
Mocked with recorded output |
test_jobs.py: exit codes, verification, auth failures (126/127), invalid ids, private files, concurrency, interrupted operations, confirmation |
Mocked processes |
test_nix_helper.py: validation, JSON-only name passing, build/activation failure rollback, removal rules, journal recovery, flake command |
Mocked build/activation |
checks.pacman-integration |
Real pacman 7.0 against a local test repository |
checks.vm |
NixOS VM: declarative package installed; sources detected (Nix system mode, Flatpak needs remote, Pacman refused on NixOS); unauthorized helper use refused; invalid/unknown names change nothing; journal recovery; user-writable list refused |
Live tests performed on the development workstation (NixOS 26.05, Noctalia 5.0.1, Niri 26.04), in an isolated nested Noctalia instance:
- Flatpak (user, Flathub): search with icons and metadata; install of
net.sourceforge.ExtremeTuxRacerthrough the panel (Enter → confirmation → Ctrl+Enter), verified withflatpak info; removal the same way, verified; installed list and real update detection. - Nix profile mode: search of 23 857 packages; install of
hello(binary ran), removal, refusal to remove a profile package the installer had not installed, refusal of unconfirmed operations. - Not performed live: a declarative NixOS rebuild (requires the administrator password; covered by the mocked transaction tests and the VM safety test), Flatpak system-installation operations, Pacman installs on Arch.
MIT — see LICENSE.


