# How to Run Pending Migrations in Omarchy: Complete Command Guide

> Learn how to run pending migrations in Omarchy using the omarchy-migrate command. Execute or list unapplied scripts easily with this complete guide.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-27

---

**Run `omarchy-migrate` to execute all pending configuration migrations, or use the `--pending` flag to list unapplied scripts without running them.**

Omarchy, Basecamp's Arch Linux-based workstation configuration system, relies on a shell-based migration framework to evolve user configurations safely across updates. To run pending migrations in Omarchy, administrators invoke the `omarchy-migrate` command, which manages execution state through marker files and enforces atomic, idempotent configuration changes.

## Understanding the Migration Architecture

Omarchy migrations are simple **shell scripts** stored in the `migrations/` directory of the repository. Each script represents a discrete configuration change that must run exactly once per user environment.

According to the file layout documentation in [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md), the system tracks completion by creating marker files in the user's state directory:

- **Source scripts**: Located in `migrations/` (e.g., [`migrations/1787494718.sh`](https://github.com/basecamp/omarchy/blob/main/migrations/1787494718.sh))
- **Completion markers**: Stored in `$XDG_STATE_HOME/omarchy/migrations/` (typically `~/.local/state/omarchy/migrations/`)

When `omarchy-migrate` executes, it compares the script names in the source directory against existing markers to determine pending work.

## How to Run Pending Migrations in Omarchy

The primary interface is the `omarchy-migrate` command located at `bin/omarchy-migrate`.

### Apply All Pending Migrations

To execute all unapplied migrations:

```bash
omarchy-migrate

```

This command:
1. Waits for any active Pacman transaction to complete (preventing package conflicts)
2. Scans the `migrations/` folder for scripts lacking completion markers
3. Runs each pending script with `bash -euo pipefail` for strict error handling
4. Creates a marker file upon zero-exit status, or aborts on failure

### List Pending Migrations Without Applying

To preview which migrations remain without executing them:

```bash
omarchy-migrate --pending

```

This is useful for CI pipelines, automated health checks, or verifying update readiness before applying changes.

### Integration in Custom Scripts

Below is a robust pattern for incorporating migration checks into deployment automation:

```bash
#!/bin/bash
set -euo pipefail

# Check for pending work first

if omarchy-migrate --pending | grep -q "Pending migrations"; then
    echo "Applying Omarchy configuration migrations..."
    if ! omarchy-migrate; then
        echo "Migration failed. Manual intervention required."
        exit 1
    fi
fi

```

## The Migration Execution Flow

As implemented in `bin/omarchy-migrate`, the execution process follows strict safety semantics:

**Pacman Transaction Safety**
The runner first acquires the Pacman lock to ensure no package installation conflicts with configuration changes. This prevents race conditions during system updates.

**Strict Execution Mode**
Each migration runs under `bash -euo pipefail`, meaning:
- **`-e`**: Exits immediately on command failure
- **`-u`**: Treats unset variables as errors
- **`-o pipefail`**: Propagates pipeline failures

**Atomic Completion Tracking**
A zero exit status automatically creates a marker file in `$XDG_STATE_HOME/omarchy/migrations/`, permanently marking that migration as complete for the current user. A non-zero exit aborts the current run but leaves the migration pending for the next invocation.

## Automatic Migration During Updates

According to [`docs/update-process.md`](https://github.com/basecamp/omarchy/blob/main/docs/update-process.md), the `omarchy update` command automatically invokes `omarchy-migrate` after Pacman finishes updating packages. This ensures that configuration changes required by new Omarchy versions apply immediately after software updates.

To manually trigger the full update workflow including migrations:

```bash
omarchy update

```

## Desktop Notifications for Pending Migrations

Omarchy includes a systemd-based notification system to alert users of pending work:

- **`default/systemd/user/omarchy-migrate-notify.service`**: A user service that triggers on graphical login
- **`bin/omarchy-migrate-notify`**: The wrapper script that executes `omarchy-migrate --pending`

When the notification service detects unapplied migrations, it surfaces a desktop toast prompting the user to run `omarchy-migrate`. This mechanism ensures that long-running desktop sessions do not miss critical configuration updates.

## Summary

- **Primary command**: `omarchy-migrate` runs all pending migrations atomically
- **Preview mode**: `omarchy-migrate --pending` lists unapplied scripts without execution
- **State tracking**: Completion markers stored in `$XDG_STATE_HOME/omarchy/migrations/`
- **Safety features**: Waits for Pacman locks, uses `bash -euo pipefail`, aborts on first failure
- **Automatic execution**: `omarchy update` calls the migration runner after package updates
- **Notification**: `omarchy-migrate-notify.service` alerts users to pending work at login

## Frequently Asked Questions

### What happens if a migration script fails?

If a migration exits with a non-zero status, `omarchy-migrate` immediately aborts the current run. The script retains its "pending" status because no completion marker is created. You must fix the underlying issue and rerun `omarchy-migrate` to apply the failed migration and any subsequent ones.

### Where are migration scripts stored in the Omarchy repository?

Migration scripts reside in the `migrations/` directory at the repository root. For example, [`migrations/1787494718.sh`](https://github.com/basecamp/omarchy/blob/main/migrations/1787494718.sh) demonstrates the standard pattern for marking completion on successful execution. The `bin/omarchy-migrate` command scans this directory to discover available migrations.

### How can I check if migrations are pending without applying them?

Use the `--pending` flag: `omarchy-migrate --pending`. This checks `$XDG_STATE_HOME/omarchy/migrations/` for missing completion markers and lists the corresponding script names without executing them. The `omarchy-migrate-notify` wrapper uses this flag to determine whether to display desktop notifications.

### Does Omarchy run migrations automatically?

Yes, but only during the update workflow. When you run `omarchy update`, the command automatically invokes `omarchy-migrate` after Pacman completes package installations. However, migrations do not run automatically on login or at arbitrary intervals; they require either manual execution or the explicit update command sequence documented in [`docs/update-process.md`](https://github.com/basecamp/omarchy/blob/main/docs/update-process.md).