Updating

Updating

syn-update keeps an installed SynapseOS current with the project's own components — synui, synapd, synguard and the rest. It is separate from pacman -Syu, which updates Arch.

You need both. They cover different halves of the system.

	Updates	Run it with
pacman -Syu (or Update System in the start menu)	Arch packages — kernel, Mesa, Qt, everything from the Arch repos	sudo pacman -Syu
syn-update (or SynapseOS Updates in the start menu)	The SynapseOS components themselves	syn-update check

If you installed from an ISO older than 0.2.3, your SynapseOS components have never been updated. See Why this exists below — this is worth reading once, because the old behaviour failed silently.

---

Quick start

syn-update check     # read-only: fetch and show what would change
syn-update apply     # rebuild the changed components and install them
syn-update status    # source revision and installed versions

check is the default, so bare syn-update is safe. It is also available as syn update.

There is a GUI — SynapseOS Updates in the start menu. It owns the read-only half and hands apply to a terminal window, deliberately: apply needs to run sudo pacman -U partway through a build, and sudo with no controlling terminal cannot prompt for a password. An in-window apply would fail at the install step, minutes into a build.

Note the start menu has two update entries, and they are not the same thing. Update System is Arch. SynapseOS Updates is this. Conflating them is how a machine ends up fully patched on the Arch side while its compositor sits hundreds of releases behind.

---

How it works

syn-update clones the project's git repository to /var/lib/synapse-src, compares each component's pkgver/pkgrel at the remote revision against what is installed, and rebuilds only what changed. Builds go through makepkg, so components are compiled on your machine rather than downloaded as binaries.

After installing, it republishes the built packages into the local repository at /var/cache/synapseos and rebuilds that repository's index. This matters: without it, a later pacman -S synui to repair an install would happily fetch the stale version the ISO shipped.

The source tree is chowned to the user who invoked the command, because makepkg refuses to run as root.

Options

Option	Effect
--force	With apply: discard local changes in the source tree
--ref <branch>	Track a branch other than main

Environment variable	Default
SYN_UPDATE_REPO	The SynapseOS GitHub repository
SYN_UPDATE_REF	main
SYN_UPDATE_SRC	/var/lib/synapse-src

---

Requirements

Because it builds from source, syn-update needs a toolchain. It depends on bash, git, base-devel, pacman and sudo, all of which pacman resolves from core — roughly 17 packages, ~118 MiB on a system that has none of them.

cmake and meson are deliberately not hard dependencies. makepkg -s pulls each component's own makedepends on demand, so you only pay for what you actually build. Hard-depending on cmake would add ~150 MiB for a component syn-update does not update anyway.

---

What it does not update

Some components are on the ISO but are not rebuilt this way. syn-update reports these rather than skipping them silently — a component quietly frozen forever is the exact bug this tool exists to fix.

Component	Why not
synapse-llama	Packaged from a staging tree that only exists during an ISO build
linux-wallpaperengine	Its build fetches a ~1.3 GB CEF blob and needs ~6 GB of scratch
chibi	371 MB of bundled voice models; the rebuild cost is all download, no source change
scenefx0.5, vibe, samsung-m2020	No build rule for them yet
shelly-bin	Its PKGBUILD downloads a pinned upstream release binary

These move with an ISO upgrade instead.

Components that are not installed are left alone. syn-update updates a system; it does not add software to it.

---

Why this exists

Every system installed from an ISO before 0.2.3 was given a package repository that could never change:

[synapseos]
SigLevel = Optional TrustAll
Server = file:///var/cache/synapseos

That directory is copied off the ISO at install time and nothing ever writes to it again. So pacman -Syu faithfully upgraded all of Arch and could never see a newer synui, synapd or synguard. An installed SynapseOS was frozen at whatever ISO installed it — and, worst of all, with no error to notice. The update command succeeded, reported nothing to do for the SynapseOS packages, and was wrong.

syn-update closes that hole, and it lists itself among the components it can update — an updater that cannot update itself would need an OS reinstall to fix, which is the dead end being removed.

---

Troubleshooting

syn-update apply fails at the install step with a sudo error. apply runs sudo pacman -U mid-build and needs a terminal to prompt on. Run it from a terminal, not from a launcher or a script with no tty. The GUI does this for you.

It reports a component as unsupported. That is intentional and not an error — see the table above. Those components come with an ISO upgrade.

pacman offers to downgrade a SynapseOS package after an update. That was a real bug in syn-update 0.1.0-6 and earlier, where the local repository kept advertising versions older than what was installed. Update syn-update itself first, then re-run.

Nothing happens and no error appears. Check syn-update status for the source revision it is actually tracking. If the tree at /var/lib/synapse-src has local modifications, apply will refuse to clobber them without --force.

---

See also: Commands · Installation · Building and Packaging · Cutting an ISO Release