# Omarchy Migration Scripts: Location and Execution Guide > Find Omarchy migration scripts in the migrations directory and learn how to execute them with the omarchy-migrate command. Track progress effortlessly. - Repository: [Omacom/omarchy](https://github.com/omacom/omarchy) - Tags: how-to-guide - Published: 2026-09-05 --- **Omarchy migration scripts** reside in the `migrations/` directory at the repository root, utilize numeric filenames to determine execution order, and are processed by the `omarchy-migrate` command which tracks completion status in `$XDG_STATE_HOME/omarchy/migrations/`. Omarchy, the open-source system configuration framework maintained by **omacom**, relies on a structured migration system to apply system updates reliably across different environments. Understanding where these **Omarchy migration scripts** are located and how the execution engine processes them is critical for system administrators troubleshooting update failures or extending the platform. ## Where Omarchy Migration Scripts Are Located The migration infrastructure lives in the **`migrations/`** directory at the root of the omacom/omarchy repository. Each migration is a self-contained Bash script whose filename consists of a numeric Unix timestamp followed by the `.sh` extension (e.g., [`1788124236.sh`](https://github.com/omacom/omarchy/blob/main/1788124236.sh)). This numeric prefix ensures deterministic ordering when sorted lexicographically. According to the source tree, the directory structure follows this pattern: - **Directory:** `migrations/` — Contains all system-wide migration scripts - **Example file:** [`migrations/1788124236.sh`](https://github.com/omacom/omarchy/blob/main/migrations/1788124236.sh) — Demonstrates privileged action handling All scripts in this directory are plain text and executable, designed to run with `bash -euo pipefail` to ensure strict error handling during system modifications. ## How the omarchy-migrate Command Executes Scripts Execution is handled by the **`omarchy-migrate`** wrapper script installed under `bin/` in the repository. This command serves as the orchestration layer between the raw migration scripts and the system's state tracking mechanism. ### The Execution Workflow When invoked without arguments, `omarchy-migrate` performs the following steps: 1. **Discovery:** Scans the `migrations/` directory for files matching the `*.sh` pattern. 2. **Sorting:** Orders discovered scripts lexicographically by filename, ensuring ascending numeric execution (e.g., [`1788124235.sh`](https://github.com/omacom/omarchy/blob/main/1788124235.sh) runs before [`1788124236.sh`](https://github.com/omacom/omarchy/blob/main/1788124236.sh)). 3. **Execution:** Runs each pending script using `bash -euo pipefail` to enforce strict error handling and pipeline failure detection. 4. **Completion Tracking:** If a script exits with status zero, `omarchy-migrate` creates a marker file under `$XDG_STATE_HOME/omarchy/migrations/` to prevent re-execution on subsequent runs. ### Command-Line Interface The migration runner supports operational flags for administrative visibility: ```bash # Execute all pending migrations (standard post-update flow) omarchy-migrate # Display pending migrations without executing them omarchy-migrate --pending ``` ### Systemd Integration and Notifications The migration system integrates with **`omarchy-migrate-notify`**, a systemd service that monitors for pending migrations. When unapplied scripts exist, this service displays desktop notifications prompting the user to execute `omarchy-migrate` manually, typically from a terminal where privilege escalation is possible. ## Anatomy of an Omarchy Migration Script Migration scripts follow a standardized Bash template. As implemented in [`migrations/1788124236.sh`](https://github.com/omacom/omarchy/blob/main/migrations/1788124236.sh), scripts must handle both standard system modifications and privilege escalation gracefully: ```bash #!/usr/bin/env bash # Example migration – file name: 1788124236.sh set -euo pipefail # … perform actions, e.g. modify config files, adjust system settings … # If privileged actions are required, print a helpful message: echo "Administrator privileges are required to apply this migration. Run omarchy-migrate again from a terminal." >&2 ``` The `set -euo pipefail` directive ensures that any command failure, unset variable, or pipeline error immediately terminates the script, preventing partial system states. Scripts requiring root access should output clear instructions to stderr rather than failing silently. ## Summary - **Omarchy migration scripts** are stored in the `migrations/` directory at the repository root, using numeric filenames (Unix timestamps) to determine execution sequence. - The `omarchy-migrate` command in `bin/` handles execution, sorting scripts lexicographically and running them with `bash -euo pipefail`. - Completion state is tracked via marker files in `$XDG_STATE_HOME/omarchy/migrations/`, preventing duplicate execution. - Use `omarchy-migrate --pending` to audit unapplied migrations before execution. - The `omarchy-migrate-notify` systemd service alerts users when manual migration intervention is required. ## Frequently Asked Questions ### Where are Omarchy migration scripts stored in the repository? Omarchy migration scripts are located in the **`migrations/`** directory at the root of the omacom/omarchy repository. Each file uses a numeric naming convention (e.g., [`1788124236.sh`](https://github.com/omacom/omarchy/blob/main/1788124236.sh)) to ensure proper ordering during execution. ### How does Omarchy determine which migration scripts to run? The `omarchy-migrate` command sorts all `*.sh` files in the `migrations/` directory lexicographically by filename. It then compares these against completion markers stored in `$XDG_STATE_HOME/omarchy/migrations/`. Only scripts lacking marker files are executed, ensuring each migration runs exactly once. ### Can I check for pending migrations without executing them? Yes. Run `omarchy-migrate --pending` to list all migration scripts that have not yet been applied to the system. This displays the numeric identifiers without triggering execution, allowing administrators to review pending changes. ### What happens if a migration script requires administrator privileges? If a script encounters a privileged operation, it should print an informative message to stderr (as seen in [`migrations/1788124236.sh`](https://github.com/omacom/omarchy/blob/main/migrations/1788124236.sh)) and exit. The `omarchy-migrate-notify` systemd service will then prompt the user to re-run `omarchy-migrate` from an interactive terminal where they can provide credentials.