garuda-health
garuda-health is the health checker of Garuda Linux. It runs a fixed list of checks, prints each problem it finds grouped by severity, and offers fixes for some of them. garuda-update runs it at the end of every update. The Toolbox offers it as “System health check” and “Repair system health”.
Running it
Section titled “Running it”garuda-health| Option | Description |
|---|---|
--fix | Apply the fixes offered for the printed issues, then run the checks again. See Applying fixes. |
--json | Print the results as JSON. Cannot be combined with --fix. |
--debug | Print the run time of each check and the errors of checks that failed to run. |
--forcetty | Keep colored output when the output is not a terminal. |
--ignore-live | Run the checks on a live system too. Without it, garuda-health prints a notice and exits on live systems. |
Severity levels
Section titled “Severity levels”Only the levels CRITICAL, HIGH, LOW and INFO are printed. Each printed issue shows (fix available) when a fix exists.
| Level | Printed as | Meaning | Effect on exit code |
|---|---|---|---|
| CRITICAL | --- CRITICAL --- | The system may not boot or update. Act on these first. | Exit code 1 |
| HIGH | --- HIGH --- | A serious problem, for example a missing kernel or a full disk. | Exit code 1 |
| LOW | --- LOW --- | A minor problem or cleanup task. | Exit code 1 |
| INFO | --- INFO --- | A suggestion, for example an optional package or a hardware hint. | No effect |
| ERROR | not printed | The check could not run. It is left out of the checks run count. | No effect |
| NOT_APPLICABLE | not printed | The check does not apply, for example because the tool it needs is missing. | No effect |
| NO_ISSUE | not printed | The check passed. | No effect |
The report starts with the number of checks that ran, for example 26/26 checks run. The denominator is the number of active checks. Checks that ended with ERROR are not counted in the numerator.
If no issue is printed, the report ends with System health check passed. No issues found.
Applying fixes
Section titled “Applying fixes”--fix applies the fixes attached to the printed issues, in order of priority from highest to lowest. It then runs all checks again.
- Most fixes print the command and ask
Continue? [y/N]before they run. The update fix runsgaruda-updatewithout this question.garuda-updatethen asks for its own confirmation. - When a fix succeeds, the fixes it excludes are skipped. A successful
garuda-update remote fixskips the update fix. - Commands that need root use
sudo, orgaruda-updateelevates itself. - The summary after a
--fixrun can show the counts from the first run. The list of remaining issues is current.
Bypass
Section titled “Bypass”Only the bootloader check has a bypass. The bypass is a file in /etc/garuda/garuda-health/. The check skips itself while the file exists. The other checks have no bypass in the code. Their only options are to fix the cause or to remove the package they check.
- Create the bypass file for the bootloader check:
sudo touch /etc/garuda/garuda-health/bypass-wrong-bootloader-check - Run
garuda-healthagain. The message"Garuda" is not the current bootloaderno longer appears. - To enable the check again, remove the file:
sudo rm /etc/garuda/garuda-health/bypass-wrong-bootloader-check
The message links to the page Why the Garuda bootloader, which explains how to make the Garuda entry the default.
Checks
Section titled “Checks”garuda-health runs 26 checks. They are listed below by group. Messages are shown as printed. Text in <...> is replaced by the names or values found on the system.
Packages
Section titled “Packages”| Check | Severity | Printed message | Fix |
|---|---|---|---|
| Core packages | CRITICAL | Core garuda linux packages are missing: <packages> | Install with sudo pacman -S |
| Important packages | HIGH | Important garuda linux packages are missing: <packages> | Install with sudo pacman -S |
| Optional utilities | INFO | Optional garuda linux utilities are missing: <packages> | Install with sudo pacman -S |
| Deprecated or removed packages | LOW | Deprecated/Outdated/Removed packages should be removed: <packages> | Remove with sudo pacman -Rs |
| PackageKit | LOW | PackageKit is currently installed. PackageKit (Discover, GNOME Software) is not a supported method to manage packages on Garuda Linux. | Remove with sudo pacman -Rs |
| Pacman configuration | CRITICAL | Pacman configuration file is missing | garuda-update remote fix |
| Pacman configuration | CRITICAL | Pacman configuration file is missing required repositories | garuda-update remote fix |
| Pacman configuration | INFO | Pacman configuration file does not have the multilib repository enabled | None |
The core group checks base, chaotic-keyring and chaotic-mirrorlist. The important group checks garuda-common-settings, garuda-update, garuda-libs and garuda-config-agent. The optional group checks garuda-toolbox, garuda-hardware-tool and garuda-system-maintenance.
The deprecated group checks garuda-hotfixes and steam-native-runtime. For steam-native-runtime, the fix first marks steam as explicitly installed when it is not. See garuda-migrations for the status of garuda-hotfixes.
The pacman configuration check requires the repositories [garuda], [core], [extra] and [chaotic-aur] in /etc/pacman.conf.
Hardware and drivers
Section titled “Hardware and drivers”| Check | Severity | Printed message | Fix |
|---|---|---|---|
| NVIDIA drivers | INFO | Nvidia drivers are not installed | sudo garuda-hardware-tool --nonfree |
| NVIDIA drivers | INFO | Nvidia drivers are installed, but no hardware profile is active | sudo garuda-hardware-tool --nonfree |
| NVIDIA drivers | INFO | Nvidia drivers are installed, but an incorrect or a suboptimal hardware profile is active | sudo garuda-hardware-tool --nonfree |
| NVIDIA kernel module | HIGH | Nvidia kernel module is not loaded | None |
| NVIDIA kernel modules | HIGH | Nvidia kernel module is not installed for the following kernels: <kernels> | sudo dkms-rebuild, only when NVIDIA sources exist in /usr/src |
| dracut | INFO | System is not using dracut for initramfs | Install garuda-dracut-support |
| dracut | HIGH | System is using dracut, but garuda-dracut-support is not installed | Install garuda-dracut-support |
| PipeWire | INFO | System is not using PipeWire for audio | Install pipewire-support |
| PipeWire | LOW | System is using PipeWire, but pipewire-support is not installed | Install pipewire-support |
The NVIDIA drivers check runs only when garuda-hardware-tool is installed. The NVIDIA kernel module checks run only when an NVIDIA module package is installed. The kernel module check looks for nvidia.ko in the kernel’s updates/dkms directory, its extramodules directory and the kernel directory itself.
The CPU temperature check exists in the code but is disabled, because the code marks it as unreliable with false positives.
Storage and Btrfs
Section titled “Storage and Btrfs”| Check | Severity | Printed message | Fix |
|---|---|---|---|
| Root Btrfs free space | HIGH | Root Btrfs filesystem has less than 5GB free space | None |
| Root Btrfs free space | LOW | Root Btrfs filesystem has less than 10GB free space | None |
| Btrfs maintenance timers | LOW | Btrfs maintenance timers are not enabled: <timers> | Enable with systemctl enable |
| Old Btrfs snapshots | LOW | Old Btrfs snapshots found that can be deleted | sudo snapper-tools delete-old |
| Snapper services | INFO | Snapper (automatic btrfs system restore) is not installed and configured | Install snapper-support |
| Snapper services | INFO | Snapper (automatic btrfs system restore) is not using the official Garuda Linux configuration | Install snapper-support |
| Snapper services | LOW | Snapper cleanup timer is not enabled | Enable snapper-cleanup.timer |
| Snapper configuration | HIGH | Snapper configuration for root is missing | garuda-update remote reset-snapper |
| Snapper configuration | HIGH | Snapper snapshots directory is missing | garuda-update remote reset-snapper |
The Btrfs free space check reads the estimated free space from btrfs filesystem usage /. It prints the HIGH message below 3000 MB and the LOW message below 10000 MB. The HIGH message text says 5GB, while the threshold in the code is 3000 MB.
The Btrfs maintenance timers are btrfs-scrub.timer, btrfs-balance.timer and btrfs-defrag.timer. The old snapshot check runs snapper-tools find-old through pkexec, so it can ask for a password.
Boot and updates
Section titled “Boot and updates”| Check | Severity | Printed message | Fix |
|---|---|---|---|
| Partial upgrade | CRITICAL | System is partially upgraded | garuda-update |
| Outdated system | HIGH | System is outdated (last update more than 2 weeks ago) | garuda-update |
| Pending reboot | INFO | A reboot is pending (update applied since last reboot) | None |
| Initramfs build | CRITICAL | Pacman hooks report that the initramfs build has failed. System may not boot. | sudo dracut-rebuild |
Kernels in /boot | CRITICAL | No (intended) kernels are installed in /boot | sudo dracut-rebuild |
Kernels in /boot | CRITICAL | Kernels in /boot are invalid (do not match expected files) | sudo dracut-rebuild |
Kernels in /boot | HIGH | The following kernels are missing in /boot: <kernels> | sudo dracut-rebuild |
Kernels in /boot | HIGH | The following kernels in /boot are invalid: <kernels> | sudo dracut-rebuild |
| Bootloader | LOW | "Garuda" is not the current bootloader: https://wiki.garudalinux.org/why-garuda-bootloader | None, see Bypass |
The partial upgrade check reads the flag file /var/lib/garuda/partial_upgrade. The outdated check and the pending reboot check read the timestamp file /var/lib/garuda/last_update. The outdated check uses 14 days as the limit. The pending reboot check compares that timestamp with the boot time.
The initramfs check reads /var/lib/garuda/initramfs_error, which the dracut hook writes when the initramfs build fails. The kernel checks compare each kernel in /usr/lib/modules with its vmlinuz and initramfs files in /boot. When /etc/garuda/secureboot/enabled exists, the byte comparison of the kernel image is skipped.
The bootloader check runs only on UEFI systems with efibootmgr installed. It reads the label of the current boot entry.
System
Section titled “System”| Check | Severity | Printed message | Fix |
|---|---|---|---|
| Failed services | LOW | Failed systemd services found: <units> | None |
| Time sync | HIGH | NTP is not enabled, system time may not be synchronized | sudo timedatectl set-ntp true |
| SMART status | CRITICAL | SMART status for <device> is failing | None |
| Available RAM | HIGH | Available RAM is below 10% of total RAM: <value> MB | None |
| Available RAM | HIGH | Available RAM is below 5% of total RAM: <value> MB | None |
| Available RAM and swap | HIGH | Available RAM and swap are both below 15% of total: <value> MB available RAM, <value> MB available swap | None |
The SMART check needs smartctl, root rights and a physical machine. It runs smartctl --scan and then smartctl -H for each disk. A disk is reported when the output says the test failed or when no PASSED line appears. The RAM check uses 10% of total RAM when no swap exists. With swap, it uses 5% and then the combined 15% rule.
Related pages
Section titled “Related pages”- garuda-update runs this check at the end of every update.
- garuda-update fixes lists the fixes that
garuda-updateapplies and offers. - garuda-config-agent manages the configuration files that the NVIDIA, Btrfs and pacman checks depend on.
- garuda-migrations applies the migrations that the health checks report on.