Skip to content

Software

Jump to bottom
Velle Sinclair edited this page Sep 3, 2026 · 5 revisions

Software

synpkg is SynapseOS's package manager — one program over the five places software on this system comes from. It is a single C binary built on libalpm (the library pacman itself uses), with three front-ends that all read the same code paths, so they cannot disagree about what is installed:

Front-end Command
Graphical browser Software Manager in the start menu, or synpkg gui
Terminal browser synpkg tui (or bare synpkg on a terminal)
Command line synpkg search, synpkg install, …

It works over SSH and on a headless machine — the GUI is an optional extra, and each front-end degrades to the one below it rather than failing.

The five sources

Every source gets its own tab in the GUI, and every row carries a coloured badge naming where it came from. That is deliberate: these are not interchangeable, and installing from one is not the same act as installing from another.

Tab What it is What actually installs it
All sources Not a source — one search across every one of them at once whichever source the row came from
Repositories Arch's core, extra, multilib, plus SynapseOS's own [synapseos] pacman. Signed binaries, built by Arch or by us.
AUR The Arch User Repository — build recipes, not binaries makepkg, on your machine. Opens a terminal so you can read the PKGBUILD first.
Flathub Sandboxed applications shipping their own runtimes flatpak, with its own permission prompts. Installed alongside your system, not into it.
Arsenal ~5000 BlackArch security tools, browsable by category pacman, once the BlackArch repo is enabled.
SynapseOS This system's own components syn-update, which rebuilds them from git. See Updating.

Searching all of them at once

All sources asks the repositories, BlackArch, the AUR and Flathub the same question and puts the answers in one list, each row badged with where it came from. It is the tab to reach for when you do not already know which source has the thing — which is most of the time.

synpkg search --all firefox      # the same list, on the command line
extra/firefox 148.0-1 [installed]
    Standalone web browser from mozilla.org
blackarch/firefox-decrypt 1.1.1-2
    Tool to extract passwords from Mozilla profiles
aur/firefox-nightly 156.0a1-1 (412 votes)
    Standalone web browser from Mozilla — nightly build
flathub/org.mozilla.firefox  Firefox 154.0
    Fast, Private & Safe Web Browser

The three single-source tabs stay, because "search only the AUR" is a real question and answering it out of four hundred rows from everywhere is not the same thing.

Every source fails alone. No network, no flatpak, no Flathub remote and no BlackArch repo are all ordinary, and none of them stops the others answering — the repository hits are on screen while the slow halves are still working. If BlackArch is not enabled, --all says so rather than returning nothing and letting you conclude it had nothing.

Two of these are off until you turn them on. A source that is switched off looks exactly like a source with nothing in it, so synpkg about reports the state of each one, and the GUI offers a button where the fix is a command.

synpkg about                     # which sources are wired up on this machine
synpkg flatpak enable-flathub    # add the Flathub remote and fetch its index
synpkg arsenal enable-repo       # bootstrap BlackArch (keys, mirrors)

Enabling Flathub also downloads its application index. Without that index flatpak search returns nothing and reports no error — which reads as "Flathub is empty" rather than "this is not ready yet". enable-flathub does both steps so that cannot happen to you.

AppImages — a verb, not a sixth source

synpkg appimage install ~/Downloads/thing.AppImage
synpkg appimage list
synpkg appimage remove <name>

install does the mechanical work nobody gets right by hand: puts the image in ~/Applications (the directory appimaged and AppImageLauncher already watch), makes it executable, unpacks its .desktop and icons, rewrites Exec to an absolute path — inside the image it reads AppRun …, which resolves to nothing outside it — and records everything it placed so remove is a real uninstall.

⚠ The menu entry is named after the window's class, not the file. A dock pin keys on the app_id, which for an Electron AppImage is its StartupWMClass. Filed under any other name the dock cannot resolve a .desktop for the running window: it draws a generic icon, offers no New Window, and a pin does not survive a restart.

⛔ It cannot search and it cannot update, and it tells you so. This is deliberately not a sixth source beside the five above, because it could not keep their promises:

  • No index. Flathub has an API and the AUR has one. AppImages have no authoritative catalogue — AppImageHub exists and is stale — so there is nothing for synpkg search to reach, and it does not pretend there is.
  • No update path. Most images carry no zsync information, so an installed one is invisible to synpkg updates for ever. Both install and list say so on the spot. Replace one by installing a newer file over the top.
  • No signature. pacman verifies packages and Flatpak has ostree signing. An AppImage is a file off the internet, and install says that before it unpacks it — which it does by running it, because an AppImage is unpacked by its own runtime.

In the window

SYNAPSE Software has an AppImages tab beside the five sources: Install an AppImage… opens a file chooser, each row offers Remove, and both the tab hint and the empty state say that synpkg cannot search for or update these. A row whose file has been deleted by hand says so, because the menu entry it left behind does nothing and this is the only place that can explain it.

⚠ It is deliberately not a source tab — those carry a browse/search/installed toggle and a search box, all of which would be furniture with nothing to answer.

⚠ Nothing outside ~/Applications, ~/.local/share/applications, ~/.local/share/icons and the manifest is touched, and remove deletes only what the manifest records. A remover that walked the icon theme looking for things that might have come from an AppImage would delete somebody else's file eventually.

Everyday use

synpkg search firefox        # the repositories
synpkg install firefox
synpkg remove firefox        # takes its unneeded dependencies with it
synpkg upgrade               # full system upgrade (refreshes first)
synpkg updates               # what an upgrade would change, read-only
synpkg installed --explicit  # what you asked for, as opposed to what came along
synpkg orphans --remove      # dependencies nothing needs any more
synpkg info firefox

Other sources are subcommands, so the source is always visible in what you typed:

synpkg aur search <term>         # and: aur install, aur installed, aur updates
synpkg flatpak search <term>     # and: flatpak install/remove/updates/remotes
synpkg arsenal categories        # and: arsenal packages <category>, arsenal installed
synpkg system check              # SynapseOS's own components (via syn-update)

SynapseOS's own components count as updates. The Updates page used to see they were out of date and offer nothing that acted on them — it did not count them and "Upgrade all" skipped them — so the half of the system no other updater covers was the half with no way to update it.

synpkg upgrade is the same engine pacman -Syu is, and pacman keeps working — use whichever you prefer. Both refresh the databases before they upgrade, which is what stops you from ending up with a partial upgrade: a system whose package databases are newer than its packages, where every later install fails on a filename the mirror has already rotated away.

Two things pacman has never done

An upgrade is gated on the Arch news. Arch announces manual-intervention notices there and nowhere else — a package that needs a key imported, a config moved, a repository renamed — and a graphical Update button makes that matter more, not less: nobody reads a news feed before pressing a button. synpkg fetches the headlines, and an upgrade that would walk into one stops and shows it.

A kernel move offers a reboot. The running kernel keeps its modules in a directory the upgrade has just replaced, so after a kernel upgrade the machine can no longer load a module it did not already have — a USB device plugged in afterwards, a filesystem mounted for the first time. synpkg says so at the end of the transaction rather than leaving it to be discovered.

synpkg status reports the kernel staged for boot as well as the installed and running ones. Those are three different files and only one of them strands a machine: an entry can exist for a kernel whose modules are gone, and "installed" does not mean "bootable" does not mean "booted".

Exit codes

Every list command returns 100 for "nothing to do", distinct from 1 for failure — so a status bar or a script can tell "you are up to date" from "the check broke" without parsing any output.

The graphical browser

Software Manager in the start menu, or synpkg gui. synpkg gui <tab> opens straight onto one tab (updates, suggested, all, repo, aur, flathub, arsenal, system, about).

Every row carries its application's icon, or a monogram tinted by the row's source where there is none — most packages are not applications and have no icon at all, so a column that appeared for some rows and not others would read as icons failing to load rather than as a library not having one.

  • All sources searches every source at once, each row badged. Search-only: "browse" would mean listing four repositories together, and "installed" already has a page per source.
  • Updates is the union of all three updatable sources — repositories, AUR and Flathub — with each row badged, so you can see at a glance which half of the system is behind.
  • Suggested is a curated list of applications worth having, grouped by category, with the ones you already have marked.
  • Repositories, AUR and Flathub each have a Search and an Installed view.
  • Arsenal lists BlackArch by category, plus an "Installed tools" view — so a tool can be removed without remembering which of ~50 categories it came from.
  • About reports what is enabled and offers to fix what is not.

Two things happen in a terminal rather than in the window, on purpose:

  • A full system upgrade. It downloads for minutes and prints as it goes; a window with a spinner and no output is where people force-quit mid-transaction.
  • Any AUR install. An AUR package is arbitrary code that builds on your machine. synpkg shows you the PKGBUILD and asks before running makepkg, which needs a terminal to ask in — and which refuses to run as root, correctly.

Everything else escalates through polkit when it needs to, so the GUI itself never runs privileged.

Flatpak notes

Flatpak applications are identified by an application id — org.mozilla.firefox, not firefox. The GUI shows the human name with the id beside it; the command line takes the id.

synpkg flatpak search boxes
synpkg flatpak install org.gnome.Boxes
synpkg flatpak remotes           # which remotes are configured

Anything synpkg does not wrap is passed through to flatpak unchanged, so synpkg flatpak permissions <id> works without needing us to have thought of it.

See also

SynapseOS Wiki

Using it

Customising it

Components

Apps

Hacking on it

Repository · Releases

Clone this wiki locally