garuda-update fixes

This page lists the fixes that garuda-update applies on its own, the retries it makes when pacman fails, and the manual rescue commands. The system checks that offer their own fixes are listed on garuda-health.

garuda-update consists of the entry script, main-update and the helper scripts update-helper-scripts and auto-pacman. The helper scripts run in a fixed order. This page follows that order.

Automatic fixes

Before the update

Step	Runs when	What it changes
Snapshot boot guard	Every run. The run stops when the system is booted into a Snapper snapshot, unless GARUDA_SNAPSHOT_PACMAN is set.	Nothing. The run stops before any change.
Sleep inhibit	Every run when systemd-inhibit exists.	Blocks sleep and shutdown while the update runs.
Log file	Every run.	Writes the output to /var/log/garuda/garuda-update. Logrotate rotates it daily or when it grows past 2 MB and keeps 7 files.
Garuda repository	Every run.	Edits /etc/pacman.conf. Renames [testing] to [core-testing] and [community-testing] to [extra-testing]. Removes [community]. Keeps one [garuda] section that includes the Chaotic-AUR mirrorlist and adds it when it is missing.
Mirrorlist refresh	Every run, unless --skip-mirrorlist or SKIP_MIRRORLIST=1 is set.	Uses rate-mirrors when it exists, otherwise reflector. A new mirrorlist is written to /etc/pacman.d/mirrorlist only when it has at least 10 server lines with rate-mirrors or 5 with reflector. A successful refresh forces a full database refresh with pacman -yy.
Self-update	Every run.	Runs pacman -Sy. When garuda-update has an upgrade, it reinstalls the package and restarts itself with the new version.
Emergency hotfix	Only when the self-update fails.	See Emergency hotfix.
Keyring update	When archlinux-keyring, chaotic-keyring or blackarch-keyring (if installed) has an upgrade.	Installs the keyring packages first with --noconfirm. The update then runs the self-update check again.
Intervention steps	Depends on the intervention sequence. The snapshot hook step runs on every update.	See Intervention sequence.
Replacement arguments	Depends on the intervention sequence and the installed packages.	Adds --ignore and replacement arguments to the pacman -Su call. See Package replacements.

During the update

Step	Runs when	What it changes
Disk space check	Before the transaction is confirmed, unless --no-space-check or NO_SPACE_CHECK=1 is set.	Declines the transaction when the free space on / is too small. The check reads the estimated free space from btrfs filesystem usage and compares it with the installed size plus the download size. The buffer is 1 GiB or 10 percent, whichever is larger.
Conflict answers	When pacman asks about a conflict.	Answers from the replacement table. See Automatic answers.
Retry on known errors	When pacman fails with a known error. Retries once.	See Retries.

After the update

Step	Runs when	What it changes
Mark as dependency	When a package was listed as a dependency for the update.	Marks the package as a dependency with pacman -D --asdeps. Used for tesseract-data-eng, which is added for spectacle.
Remove garuda-hotfixes	When the intervention sequence is below 2.	Removes garuda-hotfixes when it is installed. See garuda-migrations.
Intervention sequence	Every successful run.	Writes the current sequence number to /etc/garuda/garuda-update/intervention_sequence.
AUR update	When --aur or UPDATE_AUR=1 is set.	Runs paru -Sua or yay -Sua as the user that started garuda-update. Skipped in the Toolbox.
End routines	Every successful run.	Starts the plocate index update in the background. Starts the fish completion update, the bat cache rebuild and the micro plugin update for the user that started the run.
Update notices	Every run that has notices.	Prints the notices that the migrations wrote to /var/lib/garuda/tmp/update_notices, then deletes the file.
Health check	Every run.	Runs garuda-health. Its exit code is ignored.

Package replacements

The replacement arguments are added to the pacman -Su call. Each entry is either a replacement or an --ignore. The entries depend on the intervention sequence and on which packages are installed.

Sequence below	Installed packages	Argument added
1	python-xdg	python-pyxdg
1	pipewire-media-session with pipewire-support	--ignore pipewire-media-session
1	pipewire	--ignore pipewire-common-git
1	libretro-mame-git	--ignore libretro-mame-git
1	jack2 and pipewire-jack	--ignore jack2,lib32-jack2,jack2-dbus
1	jdk-openjdk with jre-openjdk or jre-openjdk-headless	--ignore jre-openjdk,jre-openjdk-headless
1	jre-openjdk and jre-openjdk-headless	--ignore jre-openjdk-headless
1	pinta without dotnet-runtime-7.0	dotnet-runtime-7.0
1	kwin-x11 and plasma-desktop without plasma-x11-session	plasma-x11-session
1	garuda-toolbox-git with garuda-settings-manager	--ignore garuda-toolbox-git
1	gnu-netcat	openbsd-netcat
1	garuda-dr460nized, garuda-xfce-kwin-settings, garuda-lxqt-kwin-settings or garuda-wayfire-settings with sweet-kde-git or sweet-cursor-theme-git	--ignore for the Sweet theme packages
4	proton-ge-custom	proton-ge-custom-bin
4	garuda-hardware-profile-nvidia-closed	--ignore nvidia-open-dkms
4	Mozilla certificate file missing	ca-certificates-mozilla
4	garuda-dr460nized or garuda-mokka with kwin-effects-forceblur	--ignore kwin-effects-forceblur, and kwin-effects-better-blur-dx-x11 when plasma-x11-session is installed
4	spectacle without tessdata	tesseract-data-eng

Intervention sequence

The intervention sequence records which one-time fixes have run on a system. The current value in the script is 4. The value is stored in /etc/garuda/garuda-update/intervention_sequence. The file says that it must not be changed by hand.

Sequence below	Step	When	What it changes
1	NVIDIA firmware symlinks	Before the update, when linux-firmware is older than 20250613.12fe085f-5	Removes the nvidia/ad103, ad104, ad106 and ad107 files and replaces them with symlinks to ad102. Removes the matching lines from the pacman file list of linux-firmware. This follows an Arch news item on this upgrade.
2	Remove garuda-hotfixes	After the update	Removes garuda-hotfixes when it is installed.
4	NVIDIA prime profile	Before the update, when garuda-hardware-profile-nvidia-prime-closed is installed	Marks garuda-hardware-profile-nvidia-closed as explicitly installed and removes the prime package.

The snapshot hook step has no sequence check. It runs on every update. It removes /usr/share/libalpm/hooks/01-snapshot-reject.hook when garuda-hooks version 2.15.2-1 is installed. The script comments say this disables a hook that caused a crash, and that version 2.15.3-1 enables it again.

The steps run only when the sequence is below their number. A system without the file counts as sequence 0 and runs every step once. A new install writes the file through the package’s post_install function. A system that upgrades to this version gets the file after its first successful run.

Automatic answers

auto-pacman runs pacman in an expect session. It answers the common prompts so the update can run without stopping.

• Replace X with Y [Y/n] is answered with yes.
• A conflict prompt is answered with yes when the pair is in the table below. Other conflicts are asked to the user, unless --noconfirm is set. With --noconfirm, the script stops with a message that user input is needed. On a retry, other conflicts are answered with no.
• An answer of yes that the user gives to a conflict prompt is kept for a retry in the same run.
• Enter a number (default=1) is answered with 1 when --noconfirm is set.
• Do you want to delete it (a corrupted download) is answered with yes.
• Proceed with installation is answered with yes when --noconfirm is set, or on a retry. Before that answer, the disk space check runs.

The table lists the pairs in the script. The left column is the package that pacman wants to remove. The right column is the replacement that must be part of the same conflict.

Package pacman wants to remove	Replacement
python-xdg	python-pyxdg
exe-thumbnailer	icoextract
pipewire-media-session	wireplumber
ipw2100-fw, ipw2200-fw	garuda-common-settings
firedragon-extension-xdm-browser-monitor	garuda-common-settings
qemu-base	qemu-desktop
libretro-mame-git	libretro-meta
jack2	pipewire-jack
networkmanager-fortisslvpn	networkmanager-support
ananicy-rules	cachyos-ananicy-rules-git
sweet-theme-full-git	plasma5-themes-sweet-full-git
sweet-kde-theme-git	plasma5-themes-sweet-kde-git
jre-openjdk	jdk-openjdk
jre-openjdk-headless	jdk-openjdk or jre-openjdk
plasma5-applets-window-appmenu, plasma5-applets-window-title, plasma5-applets-window-buttons	garuda-dr460nized
plasma5-applets-betterinlineclock-git, plasma5-wallpapers-blurredwallpaper, plasma-applet-window-buttons	garuda-dr460nized
alpm_octopi_utils	octopi
scenefx	swayfx
gnu-netcat	openbsd-netcat
proton-ge-custom	proton-ge-custom-bin
nvidia-utils, opencl-nvidia, nvidia-dkms	The matching -580xx package
lib32-nvidia-utils, lib32-opencl-nvidia	The matching lib32-...-580xx package
kwin-effects-forceblur	garuda-dr460nized or garuda-mokka
lib32-fluidsynth, lib32-audit, lib32-libcap, lib32-pam, lib32-gstreamer and four other lib32 multimedia packages	wine-meta

Retries

When pacman fails, garuda-update reads its log and retries the update once for these errors.

Pacman error	Retry
invalid or corrupted package	Uses a temporary pacman configuration that points the Chaotic-AUR repository to its server directly instead of the mirrorlist.
download library error	Uses a temporary pacman configuration without ParallelDownloads.
conflicting files, only when every conflict is a Python __pycache__ .pyc file	Adds --overwrite for /usr/lib/python*/site-packages/*/__pycache__/*.pyc.

The script treats exit code 134 as success. The reason is UNCONFIRMED. A failed run after the retry stops the update, so the post-update steps and the sequence update do not run.

Emergency hotfix

The emergency hotfix replaces the removed garuda-hotfixes package. It runs only when the self-update fails.

1. garuda-update reads a version number from the Garuda web server. The script has the number 8 built in.
2. When the server number is higher, garuda-update downloads the hotfix script. The first line must be # GARUDA UPDATE HOTFIX.
3. It asks y/n/p. The answer p prints the script before the next question. The answer n continues without the hotfix.
4. On y, it runs the script with VERSION=8. When the script succeeds, garuda-update starts again.

The repository configuration returns 7 for the version check, so the question does not appear for this version. The live value is UNCONFIRMED. The hotfix script is hosted outside this repository, so its content is UNCONFIRMED.

Manual options

Command-line flags

Flag	Environment variable	Effect
--skip-mirrorlist	SKIP_MIRRORLIST=1	Skips the mirrorlist refresh.
--aur, -a	UPDATE_AUR=1	Updates AUR packages after the system update.
--noconfirm	PACMAN_NOCONFIRM=1	Answers prompts automatically. Stops when user input is needed.
--no-space-check	NO_SPACE_CHECK=1	Skips the disk space check.
-U, --upgrade	none	Installs the given package files with pacman -U instead of a system update.
-- <pacman options>	PACMAN_EXTRA_OPTS	Passes extra options to pacman.
--help, -h	none	Shows the help text.

Other environment variables used by the script are PACMAN_EXE, which replaces the pacman binary, and GARUDA_SNAPSHOT_PACMAN, which allows an update while booted into a snapshot. The settings can also be stored in /etc/garuda/garuda-update/config. The template line # NO_CHECK_SPACE=1 in that file has no effect, because the script reads NO_SPACE_CHECK. Use NO_SPACE_CHECK=1 instead.

Caution

--noconfirm answers the conflict and replacement prompts without asking. Use it only when you know which packages will change.

Remote rescue commands

garuda-update remote <command> runs a script that Garuda Linux hosts outside this repository. The script runs as root. Its exact steps are UNCONFIRMED beyond the descriptions in the help text.

Command	Description from the help text	Toolbox label
remote fix	Resets pacman.conf and refreshes the keyrings.	Garuda update fix. The Toolbox description also names the mirror lists.
remote keyring	Refreshes the keyring without resetting pacman.conf.	Garuda update keyring
remote fullfix	Resets pacman.conf, refreshes the keyrings and reinstalls all packages.	Garuda update full fix
remote reinstall	Reinstalls all packages.	Reinstall packages
remote reset-snapper	Removes all backup subvolumes and snapshots created by Snapper and recreates the Snapper configs.	Reset snapper
remote reset-audio	Reinstalls pipewire-support and WirePlumber and restarts their services.	Reset audio

Caution

reset-snapper removes Snapper snapshots. fullfix and reinstall reinstall every package. Make a backup before you run them.

Toolbox buttons

The Toolbox runs the same commands in a terminal, with the environment variable GARUDA_UPDATE_TOOLBOX=1. That variable skips the AUR update.

Button	Command
Update system	garuda-update --skip-mirrorlist
Garuda update fix	garuda-update remote fix
Garuda update keyring	garuda-update remote keyring
Garuda update full fix	garuda-update remote fullfix
Reinstall packages	garuda-update remote reinstall
Reset audio	garuda-update remote reset-audio
Reset snapper	garuda-update remote reset-snapper
System health check	garuda-health
Repair system health	garuda-health --fix

Fixes offered by garuda-health

Health result	Rescue command
Pacman configuration missing or missing a repository	garuda-update remote fix
Partially upgraded or outdated system	garuda-update
Snapper configuration missing	garuda-update remote reset-snapper

Suggested order after a failed update

1. Run garuda-update again. The retries and the intervention steps run again when they did not finish.
2. Read the log file /var/log/garuda/garuda-update for the pacman error.
3. If the error is about the repositories or the keyrings, run garuda-update remote fix.
4. Run garuda-health and read the report.