# How to Trigger Omarchy Migrations: Complete Command Reference and Automation Guide

> Learn how to trigger Omarchy migrations using the omarchy-migrate command. This guide covers command reference and automation for managing your Omakia database schema efficiently.

- Repository: [Omacom/omarchy](https://github.com/omacom/omarchy)
- Tags: how-to-guide
- Published: 2026-09-01

---

**Omarchy migrations are triggered by running the `omarchy-migrate` command, which executes pending shell scripts from the `migrations/` directory and records completion state per-user under `~/.local/state/omarchy/migrations/`.**

Understanding how to trigger Omarchy migrations is essential for keeping your Arch Linux-based system up to date. Migrations are small shell scripts that handle per-user upgrades and system repairs after package updates, making them a core part of the Omarchy maintenance workflow according to the omacom/omarchy source code.

## What Omarchy Migrations Are and Where They Live

Migration scripts in Omarchy serve as automated, idempotent upgrade procedures. Each script lives in the repository's `migrations/*.sh` directory and performs specific transition tasks when the system or user configuration needs to change.

State tracking happens per-user. When a migration completes successfully, Omarchy creates a marker file under `~/.local/state/omarchy/migrations/<script-name>`. This prevents re-execution and ensures each migration runs exactly once per user account.

## The `omarchy-migrate` Command: Core Trigger Mechanism

The primary way to trigger Omarchy migrations is through the `omarchy-migrate` script located at `bin/omarchy-migrate`. This thin wrapper handles discovery, locking, and execution with strict error handling.

### What the Command Does

- **Waits for pacman transactions** – Ensures no package manager conflicts
- **Scans `migrations/` directory** – Identifies scripts without completion markers
- **Executes with `bash -euo pipefail`** – Strict mode: exits on any error
- **Records success or failure** – Creates state marker regardless of outcome

### Running Migrations Manually

To trigger all pending migrations immediately:

```bash
omarchy-migrate

```

This executes every migration that lacks a completion marker in your user state directory, stopping at the first failure.

### Checking Pending Migrations Without Running Them

Use the diagnostic flag to preview what's queued:

```bash
omarchy-migrate --pending

```

Exit status `0` means migrations are waiting; non-zero means you're fully up to date. This flag powers automation tools and notification systems.

## Automatic Trigger Points: When Migrations Run Without Manual Action

Omarchy provides three built-in trigger mechanisms beyond manual invocation.

### After Package Updates via `omarchy update`

The standard `omarchy update` command automatically triggers migrations once Pacman finishes. The sequence is: update packages, then run `omarchy-migrate`. No separate step required.

```bash

# This triggers migrations automatically after pacman completes

omarchy update

```

### Post-Manual Pacman Upgrade

If you run `pacman` directly, trigger migrations afterward:

```bash
sudo pacman -Syu    # standard Arch system update

omarchy-migrate     # apply any new migrations the update introduced

```

### Desktop Notification Service

A per-user systemd unit handles GUI environments. The `omarchy-migrate-notify.service` (defined at `default/systemd/user/omarchy-migrate-notify.service`) runs at login and:

- Monitors for pending migrations using `omarchy-migrate --pending`
- Displays a clickable desktop notification when work is needed
- Launches `omarchy-migrate` when the user clicks the notification

No configuration required—this provides zero-friction migration triggering for desktop users.

## Migration Script Structure and Requirements

Understanding script anatomy helps when debugging or writing custom migrations.

### Standard Migration Template

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

# Migration work here

# -e: exit on error

# -u: treat unset variables as errors

# -o pipefail: pipeline fails if any command fails

# Create directories, update configs, etc.

mkdir -p ~/.config/omarchy/custom

# Exit 0 marks completion (success or handled failure)

```

### Privilege Handling

Migrations run as the current user. For tasks requiring root access, delegate to helper scripts that request administrator rights through standard mechanisms. The migration marks complete regardless of privilege-helper success to avoid infinite prompting loops.

## Migration State and Idempotency

The completion tracking system enforces single execution per user.

### State Directory Layout

```

~/.local/state/omarchy/migrations/
├── 001-fix-paths.sh      # marker file exists = completed

├── 002-update-themes.sh  # missing = pending

└── 003-new-defaults.sh   # missing = pending

```

### Idempotency Guarantees

- Script absence from state directory → eligible for execution
- Script presence in state directory → skipped permanently
- Failed scripts still create markers → no retry without manual intervention

To re-run a migration, manually remove its marker file from the state directory.

## Troubleshooting Migration Triggers

### Migrations Not Running Automatically

1. Verify the notification service is enabled: `systemctl --user status omarchy-migrate-notify.service`
2. Check for pending migrations manually: `omarchy-migrate --pending`
3. Review the update process documentation at [`docs/update-process.md`](https://github.com/omacom/omarchy/blob/main/docs/update-process.md)

### Migration Failures Abort the Queue

When one migration fails, subsequent migrations do not run. Fix the failing script or temporarily bypass it by creating its marker file manually (not recommended for production systems).

### State Directory Permissions

Ensure `~/.local/state/omarchy/` is owned by your user. Migration recording will fail silently if the state directory is unwritable.

## Summary

- **Primary trigger command:** `omarchy-migrate` executes pending migration scripts from `migrations/*.sh`
- **Automatic triggers:** `omarchy update` and systemd notification service (`omarchy-migrate-notify.service`)
- **State tracking:** Per-user completion markers in `~/.local/state/omarchy/migrations/<script-name>`
- **Diagnostic mode:** `omarchy-migrate --pending` lists queued work without executing
- **Execution model:** `bash -euo pipefail` with fail-fast behavior across the migration queue

## Frequently Asked Questions

### How do I know if I have pending Omarchy migrations?

Run `omarchy-migrate --pending`. Exit code `0` indicates pending migrations exist; non-zero means all migrations are complete. The notification service also visualizes this status graphically on desktop environments.

### Can I run Omarchy migrations as root?

Migrations are designed for per-user execution and run as the calling user. Root execution would create state markers in root's home directory, not your user's. For privileged operations, migrations should call privilege-escalation helpers rather than running as root directly.

### What happens if a migration fails?

The failing migration creates its completion marker to prevent retry loops, and `omarchy-migrate` exits immediately without running subsequent migrations. You must fix the underlying issue manually or remove the marker file to reattempt that specific migration.

### How are migrations triggered after a manual pacman update?

The `omarchy-migrate` command does not automatically detect manual `pacman -Syu` runs. You must invoke it manually after package updates when using pacman directly instead of `omarchy update`, which handles the trigger automatically.