# How Omarchy Handles User Configuration and System Defaults: A Complete Guide

> Learn how Omarchy handles user configuration and system defaults. Discover how the omarchy-refresh-config command syncs settings while preserving your customizations.

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

---

**Omarchy separates configuration into two layers—system defaults shipped in `config/` and user overrides in `~/.config`—with the `omarchy-refresh-config` command syncing them while preserving customizations through automatic backups.**

Omarchy's configuration system lets users customize their environment without losing access to upstream improvements. This dual-layer approach ensures that system defaults remain version-controlled while personal modifications survive updates. The mechanism relies on predictable file paths and a dedicated refresh command that handles merging safely.

## The Two-Layer Configuration Model

Omarchy organizes settings into distinct system and user tiers that follow the same relative directory structure.

### System-Default Configuration

Default configurations live in the **`config/`** directory at the repository root. These files are read from `$OMARCHY_PATH/config` at runtime and serve as the authoritative baseline.

Key default locations include:

- [`config/hypr/hyprland.lua`](https://github.com/omacom/omarchy/blob/main/config/hypr/hyprland.lua) — default Hyprland compositor settings
- [`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json) — core Omarchy shell definition
- [`config/herdr/config.toml`](https://github.com/omacom/omarchy/blob/main/config/herdr/config.toml) — Herdr service configuration

These paths mirror the standard XDG configuration layout, making overlay logic straightforward.

### User-Specific Configuration

User overrides reside in **`~/.config`** following identical relative paths. When Omarchy needs a configuration value, it checks the user location first, falling back to system defaults only when no custom file exists.

This design means:

- Users can copy and modify any default without touching repository files
- Upstream updates to defaults remain available for selective adoption
- No merge conflicts occur since files are never directly edited in place

## The omarchy-refresh-config Command

The **`omarchy-refresh-config`** command is the core mechanism that synchronizes defaults to user space. Implemented in `bin/omarchy-refresh-config`, it handles three critical operations: existence checking, backup creation, and validation.

### Copy-on-First-Run Behavior

When invoked, the command copies from `$OMARCHY_PATH/config/<path>` to `$HOME/.config/<path>` **only if the target does not already exist**. This ensures fresh installations receive working defaults while existing setups remain untouched.

### Automatic Backup Before Overwrite

If a user file already exists, the command first creates a `*.bak` backup before writing the new default:

```bash

# The refresh command backs up existing files automatically

omarchy-refresh-config hypr/hyprland.lua

# Creates ~/.config/hypr/hyprland.lua.bak if user version exists

```

This guarantees no custom changes are lost during intentional refreshes.

### Validation and Error Handling

The command validates that the requested configuration exists in the defaults directory. If the source file is missing, it aborts with an error rather than creating broken symlinks or empty files.

## Working with omarchy-refresh-config

### Basic Usage

Refresh a single default configuration into your user directory:

```bash
omarchy-refresh-config hypr/hyprland.lua

```

This creates `~/.config/hypr/hyprland.lua` if absent, or backs up and replaces it if present.

### Scripted Refresh with Environment Variables

For automation or testing, explicitly set the required paths:

```bash
HOME="$HOME" OMARCHY_PATH="$OMARCHY_PATH" \
omarchy-refresh-config hypr/bindings.lua

```

### Migration Script Integration

The [`migrations/1786273938.sh`](https://github.com/omacom/omarchy/blob/main/migrations/1786273938.sh) file demonstrates how Omarchy uses refresh commands during system updates:

```bash

# From migrations/1786273938.sh

[[ -f "$HOME/.config/herdr/config.toml" ]] || \
omarchy-refresh-config herdr/config.toml

```

This pattern ensures new defaults propagate to existing installations without forcing overwrites.

### Verifying Results

Confirm the refresh succeeded by checking the target location:

```bash
ls -la ~/.config/hypr/hyprland.lua

# Should show timestamp matching your refresh operation

```

## Testing and Quality Assurance

The configuration refresh mechanism includes comprehensive test coverage in [`test/shell.d/refresh-config-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/refresh-config-test.sh). These automated tests verify:

- Correct copying behavior for missing user files
- Backup creation and naming conventions
- Proper error responses for invalid source paths
- Environment variable handling

Running this suite ensures the refresh command behaves predictably across shell versions and platform variations.

## Configuration File Reference

| Role | File Path | Description |
|------|-----------|-------------|
| Default configs | [`config/hypr/hyprland.lua`](https://github.com/omacom/omarchy/blob/main/config/hypr/hyprland.lua) | Shipped Hyprland compositor configuration |
| Default configs | [`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json) | Core Omarchy shell definition |
| Default configs | [`config/herdr/config.toml`](https://github.com/omacom/omarchy/blob/main/config/herdr/config.toml) | Herdr service defaults |
| Refresh command | `bin/omarchy-refresh-config` | Implements copying, backup, and validation |
| Test suite | [`test/shell.d/refresh-config-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/refresh-config-test.sh) | Automated behavior verification |
| Migration pattern | [`migrations/1786273938.sh`](https://github.com/omacom/omarchy/blob/main/migrations/1786273938.sh) | Production usage example |

## Summary

- **System defaults** live in `config/` under the Omarchy installation path and ship with every version
- **User overrides** use matching paths in `~/.config` and take precedence at runtime
- **`omarchy-refresh-config`** syncs defaults to user space with automatic backup protection
- **Migration scripts** leverage the refresh command to distribute new configuration options safely

This architecture gives Omarchy users full customization freedom while maintaining a clear upgrade path for system improvements.

## Frequently Asked Questions

### What happens to my custom settings when I run omarchy-refresh-config?

The command creates a `*.bak` backup of any existing user file before overwriting it. Your original configuration is preserved with a timestamped backup extension, allowing recovery if the new default causes issues.

### Can I restore a previous configuration after refreshing?

Yes. Each refresh that overwrites an existing file generates a `.bak` version in the same directory. Simply rename or copy the backup file to restore your previous settings:

```bash
mv ~/.config/hypr/hyprland.lua.bak ~/.config/hypr/hyprland.lua

```

### How do I know which configuration files are available to refresh?

Examine the `config/` directory in your Omarchy installation path. Any file or subdirectory there can be refreshed using its relative path as the argument to `omarchy-refresh-config`:

```bash
find "$OMARCHY_PATH/config" -type f

```

### Does Omarchy automatically refresh configurations during updates?

No automatic refresh occurs during standard updates. However, migration scripts in the `migrations/` directory selectively refresh specific files when new defaults are required for functionality. These migrations use the same `omarchy-refresh-config` command with existence checks to avoid overwriting user customizations.