> For the complete documentation index, see [llms.txt](https://docs.monarchlinux.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.monarchlinux.com/system/updates-and-recovery.md).

# Updates and recovery

Update Monarch safely and choose the right recovery option when something goes wrong.

Use **Monarch Menu → Maintenance → Monarch** or run:

```bash
monarch update
```

The Monarch updater keeps the operating-system update in one transaction. It checks free space, prunes superseded package cache entries, attempts a system snapshot, updates Monarch and package keyrings, upgrades repository and AUR packages, reconciles the installation, removes orphaned packages, runs post-update hooks, analyses the log, and prompts for required restarts.

{% hint style="warning" %}
Do not use `sudo pacman -Syu` for routine system upgrades. Monarch blocks direct full upgrades by default because they skip parts of this pipeline.
{% endhint %}

## Check your version and available updates

To see your installed Monarch runtime version and source revision:

```bash
monarch version
monarch version --commit
```

Versions such as `2026.10.0` and `2026.10.1` identify Monarch's desktop runtime, not the versions of all installed applications.

### Update indicator in the bar

The update indicator checks for available upgrades to Monarch, other repository packages, and AUR packages. It is hidden after a complete check confirms that everything is up to date. A new Git tag alone does not mean a package upgrade is available.

When updates are available, the icon shows the total number of verified package upgrades. Its color follows the active theme, with this priority when several categories have updates:

1. **Monarch**: the `monarch` and `monarch-settings` packages (primary theme color).
2. **Repositories**: other packages from the configured system repositories (secondary theme color).
3. **AUR**: packages from the Arch User Repository (tertiary theme color).

These colors identify update categories, not security severity. Their exact appearance depends on your theme.

Hover over the indicator to see the total, the count in each category, and each package's **installed → available** versions. For example:

`monarch 2026.10.0 → 2026.10.1`

The tooltip lists Monarch packages first, then repository packages, then AUR packages, alphabetically within each category. It displays at most **12 packages**, followed by the number of additional packages. The bar counter always includes all verified updates, not just the packages visible in the tooltip.

Click the indicator to open the interactive system updater in a floating terminal. Passive checks never install packages or request sudo.

### Incomplete or failed checks

* If the AUR check fails but repository upgrades were found, the indicator keeps those upgrades available. It shows a lower-bound count such as **≥3** and marks AUR availability as **not checked**, rather than zero.
* If a check fails, the indicator uses the theme's error color. Previously known updates remain visible, but the tooltip explicitly marks them as **last known**, not a fresh result.
* If no successful result is available, the indicator shows **?**. This does not mean the system is up to date. Click it to check in the terminal and inspect any recovery prompt.

Checks run every **six hours** after a confirmed up-to-date result, or every **ten minutes** while updates are pending or verification is failing. Tooltips follow Monarch's interface language independently of Noctalia's language.

### Check from a terminal

`monarch update available` keeps its Monarch-only scope. To check all repository and AUR upgrades, use:

```bash
monarch update available --all
monarch update available --all --json
```

The JSON output includes category counts and installed/available versions. Exit status **0** means known updates are available, **1** means a complete check found none, and **2** means verification failed or remained incomplete without any known updates.

## If an update fails

Read the error shown in the terminal, correct it, and run `monarch update` again. The complete current update session is recorded at:

```
/tmp/monarch-update.log
```

Do not reboot after an initramfs-generation failure until it has been corrected. The updater explicitly reports that condition when it detects it.

The **Stable** and **Dev** channels can be selected under **Monarch Menu → Maintenance → Channel**. Stable is the normal choice; Dev receives unfinished changes and may require manual recovery.

### Package conflicts

An interactive update may ask you to confirm a package replacement. Review the question before answering; an unattended update stops if your input is needed.

A filesystem conflict stops the update and leaves the existing files in place. Do not delete or move system files solely because pacman lists them in an error. Identify the cause before retrying the update.

## System snapshots

Create a system snapshot manually:

```bash
monarch snapshot create
```

Open the snapshot restore workflow:

```bash
monarch snapshot restore
```

{% hint style="info" %}
Snapshots protect the Btrfs root system. They are not a backup of personal files in `/home`. Keep independent backups of data you cannot replace.
{% endhint %}

## Choose the smallest recovery action

| Problem                                              | Action                       | Effect                                                                                  |
| ---------------------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------- |
| Generated Niri configuration is damaged              | `monarch refresh niri`       | Rebuilds, validates, and reloads Niri while keeping `user.kdl` separate                 |
| Monarch-managed Noctalia files are damaged           | `monarch refresh noctalia`   | Backs up and restores the managed Noctalia files, then restarts the shell               |
| A system change must be rolled back                  | `monarch snapshot restore`   | Restores a selected root-system snapshot                                                |
| Default packages or configurations are badly damaged | `monarch reinstall`          | Reinstalls Monarch's default packages from Stable and overwrites default configurations |
| The machine must return to first-owner setup         | **Settings → Factory Reset** | Erases user and machine state, then starts new-owner provisioning                       |

{% hint style="danger" %}
`monarch reinstall` overwrites changes made to Monarch's default configuration files. Back up any configuration you want to keep before confirming it.
{% endhint %}

## Factory reset

Factory reset is intended for selling or handing the computer to a new owner. It requires the standard Monarch Btrfs layout and an `@factory` snapshot created by a compatible Monarch installer.

It permanently removes:

* every user account and everything in `/home`;
* packages and system changes made since installation;
* saved network connections, SSH host keys, and the machine identity.

After the staged reset, reboot to complete the wipe. The next boot starts owner provisioning like a fresh installation.

{% hint style="danger" %}
Factory reset is destructive and cannot restore personal files. On an unencrypted disk it is deletion, not guaranteed forensic erasure. On an encrypted disk, changing passphrases also does not replace the underlying volume key. Use an appropriate secure-erasure or full-reinstallation procedure when that distinction matters.
{% endhint %}