First-Run Setup vs User Finalization in Omarchy: Key Differences Explained

First-run setup handles one-time UI toasts and hardware tweaks immediately after the first graphical login, while user finalization prepares the persistent runtime environment after /etc/skel seeding completes.

The Omarchy distribution from basecamp/omarchy implements a two-stage onboarding process that separates initial user experience configuration from persistent environment preparation. Understanding the distinction between first-run setup and user finalization is essential for troubleshooting installation issues and manually reprovisioning user environments.

Execution Timing and Triggers

The primary distinction between these phases lies in when they execute during the boot-and-login sequence.

First-run setup launches automatically immediately after the first interactive login—the very first time a user reaches the graphical shell. This phase runs once per installation and is triggered by the login manager starting the omarchy-provision-first-run binary. Upon completion, the script sets a marker file at ~/.local/state/omarchy/done/first-run-user to prevent re-execution.

User finalization runs once per user after the /etc/skel seed has been copied and first-run work is finished. Unlike first-run, this phase can be re-invoked manually using the omarchy finalize user command, which executes bin/omarchy-provision-user. It leaves a completion marker at ~/.local/state/omarchy/done/finalize-user.

Core Responsibilities and Tasks

Each phase manages distinct configuration domains that cannot be interchanged.

First-Run Setup Tasks

First-run setup focuses on UI-related, one-time user experience tasks that require a running graphical session. According to the source code in install/user/first-run/, this phase includes:

• Enabling user units via install/user/first-run/enable-user-units.sh to start necessary systemd user services
• GNOME/GTK theme tweaks handled by gnome-theme.sh and gtk-primary-paste.sh
• Audio hardware tuning through audio-tuning.sh for speaker-specific configuration
• Welcome notifications displayed by welcome.sh, showing key-binding cheats as a toast notification
• Connectivity alerts managed by wifi.sh for Wi-Fi and update notifications

User Finalization Tasks

User finalization handles runtime-environment preparation that /etc/skel cannot perform during initial seeding. The main logic resides in install/user/all.sh and includes:

• Creating XDG user directories and establishing mime defaults
• Generating skill symlinks and other runtime files requiring $HOME expansion
• Running pending migrations via omarchy-migrate
• Seeding per-user configuration requiring live system detection

Idempotency and State Management

Both phases implement idempotent guards using marker files in ~/.local/state/omarchy/done/.

The first-run marker (first-run-user) ensures the provisioner runs exactly once per installation. If the script fails, the marker is cleared automatically, allowing retry on the next login.

The finalization marker (finalize-user) makes the operation safe to re-run manually. When you execute omarchy finalize user, it applies only missing configuration pieces without duplicating existing setup.

Manual Execution and Troubleshooting

You can interact with both provisioning phases manually for debugging or reconfiguration.

To force a re-run of the first-run setup after a failure:

rm -f "$HOME/.local/state/omarchy/done/first-run-user"

The next login will automatically execute the first-run scripts again.

To manually trigger user finalization or preview changes:

# Execute finalization

omarchy finalize user

# Preview changes without applying

omarchy finalize user --dry-run

For targeted debugging of specific first-run steps:

omarchy-provision-first-run --step welcome.sh

Summary

• First-run setup (bin/omarchy-provision-first-run) executes once after the first graphical login, handling UI toasts, theme configuration, and hardware-specific audio tuning.
• User finalization (bin/omarchy-provision-user via omarchy finalize user) prepares the persistent runtime environment with XDG directories and migrations after /etc/skel seeding.
• First-run triggers automatically via login manager; finalization can be run manually and is safely idempotent.
• Both phases use marker files in ~/.local/state/omarchy/done/ to prevent duplicate execution.
• First-run scripts live in install/user/first-run/ while finalization logic resides in install/user/all.sh.

Frequently Asked Questions

Can I run first-run setup or user finalization multiple times?

User finalization is designed to be re-run safely using omarchy finalize user and will only apply missing configuration. First-run setup is intended to run only once automatically, but you can force re-execution by removing the ~/.local/state/omarchy/done/first-run-user marker file before logging in again.

What happens if first-run setup fails during initial login?

If omarchy-provision-first-run encounters an error, it automatically clears the first-run-user marker file. This allows the first-run scripts to execute again on your next login, ensuring critical initial configuration like user unit enabling and theme setup eventually completes successfully.

Where does Omarchy store the completion markers for these phases?

Both phases write state files to ~/.local/state/omarchy/done/. First-run creates first-run-user while finalization creates finalize-user. These markers prevent duplicate execution and can be manually deleted to force re-provisioning when necessary.

Why can't /etc/skel handle all user finalization tasks?

The /etc/skel directory only supports static file copying during account creation. User finalization handles dynamic configuration requiring $HOME path expansion, live system detection, and migration scripts that must run after the graphical environment is fully initialized—tasks impossible to perform during initial skeleton seeding.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}