# How Omarchy Blocks Direct pacman -Syu to Protect System Updates

> Learn how Omarchy prevents direct pacman -Syu by using an ALPM hook to guard system updates. Discover how to bypass this protection when needed.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: internals
- Published: 2026-08-26

---

**Omarchy prevents direct `pacman -Syu` by installing an ALPM pre-transaction hook that runs `omarchy-update-pacman-guard`, which aborts the transaction unless the `OMARCHY_UPDATE_PACMAN` or `OMARCHY_ALLOW_DIRECT_PACMAN` environment variables are set.**

The `basecamp/omarchy` distribution maintains strict control over system updates to ensure transcript logging, snapshot creation, and migration scripts execute reliably. Instead of allowing raw package manager access, Omarchy intercepts direct upgrade attempts through a defensive hook system. This design guarantees that the Omarchy update process runs through its blessed pipeline rather than bypassing critical safety checks.

## The ALPM Hook Infrastructure

Omarchy registers a **pre-transaction hook** at `default/libalpm/hooks/00-omarchy-update-guard.hook` that pacman invokes automatically before every package operation. This hook specifies `Exec = /usr/local/bin/omarchy-update-pacman-guard` and includes the `AbortOnFail` directive, ensuring that any non-zero exit from the guard script immediately cancels the transaction. Because the hook triggers before files are modified, it provides a failsafe barrier against accidental direct upgrades.

## Guard Script Logic and Detection

The executable at `bin/omarchy-update-pacman-guard` performs three distinct validation checks to determine whether the current pacman invocation is authorized.

### Environment Variable Bypasses

The guard first inspects the process environment for two specific **environment variables**. If `OMARCHY_UPDATE_PACMAN=1` is present—set automatically by internal Omarchy commands like `omarchy-update-system-pkgs`—the script exits with status 0 to permit the operation. Users may also set `OMARCHY_ALLOW_DIRECT_PACMAN=1` to explicitly override the protection when running pacman manually.

### Argument Reconstruction and Sync Detection

When no bypass variable is detected, the script reconstructs the pacman command line by reading `/proc/$PPID/cmdline` or the `OMARCHY_PACMAN_CMDLINE` variable. It parses the arguments to detect the simultaneous presence of a **sync flag** (`-S` or `--sync`) and a **sysupgrade flag** (`-u` or `--sysupgrade`). Identifying both flags indicates a full system upgrade attempt rather than a selective package installation.

### Transaction Abort Logic

If the script confirms a direct system upgrade without authorization, it prints a warning message advising the user to run `omarchy update` instead, then exits with status 1. Because the ALPM hook uses **AbortOnFail**, this exit code forces pacman to terminate before modifying any packages. This mechanism effectively blocks `sudo pacman -Syu` while preserving the ability to install individual packages.

## Permitted Update Workflows

Omarchy provides specific pathways to run pacman safely within its controlled environment or to bypass the guard when absolutely necessary.

Run the blessed update command, which sets the required environment variable internally:

```bash
omarchy update

# Internally executes:

sudo env OMARCHY_UPDATE_PACMAN=1 pacman -Syu --noconfirm

```

Attempting a direct upgrade triggers the guard and fails:

```bash
sudo pacman -Syu

# Output:

# Woah partner...

# This looks like a direct pacman system upgrade. Omarchy updates should normally run through:

#   omarchy update

# If you really meant to bypass Omarchy for this transaction, rerun pacman with:

#   sudo env OMARCHY_ALLOW_DIRECT_PACMAN=1 pacman -Syu

```

To explicitly bypass the guard for a specific transaction:

```bash
sudo env OMARCHY_ALLOW_DIRECT_PACMAN=1 pacman -Syu

```

## Summary

- Omarchy uses an **ALPM pre-transaction hook** at `default/libalpm/hooks/00-omarchy-update-guard.hook` to intercept all pacman operations.
- The **`omarchy-update-pacman-guard`** script validates environment variables and command-line arguments to detect unauthorized system upgrades.
- Direct `pacman -Syu` attempts are aborted with exit code 1 unless `OMARCHY_UPDATE_PACMAN=1` or `OMARCHY_ALLOW_DIRECT_PACMAN=1` is set.
- The **`omarchy update`** command automatically configures the required environment to pass the guard check.
- Users can override the protection temporarily by prefixing pacman with `env OMARCHY_ALLOW_DIRECT_PACMAN=1`.

## Frequently Asked Questions

### What happens if I try to run sudo pacman -Syu on Omarchy?

The pacman transaction aborts before installing any packages. The `omarchy-update-pacman-guard` script detects the sysupgrade flag, prints a message directing you to use `omarchy update`, and exits with status 1, triggering the `AbortOnFail` hook directive.

### How do I bypass the Omarchy update guard?

Set the `OMARCHY_ALLOW_DIRECT_PACMAN` environment variable when invoking pacman: `sudo env OMARCHY_ALLOW_DIRECT_PACMAN=1 pacman -Syu`. This signals the guard script to exit with status 0 and allow the transaction to proceed.

### Why does Omarchy block direct pacman system upgrades?

According to the `basecamp/omarchy` source code, the block ensures that transcript logging, btrfs snapshot creation, migration execution, and post-update hooks run in the correct sequence. A raw `pacman -Syu` call would bypass these critical lifecycle steps and potentially leave the system in an inconsistent state.

### Where is the update guard hook installed?

The hook is defined in `default/libalpm/hooks/00-omarchy-update-guard.hook` within the Omarchy repository and installs to the system’s ALPM hooks directory. It executes `/usr/local/bin/omarchy-update-pacman-guard` before every pacman transaction.