# What Is the Purpose of the `omarchy-settings` Arch Package?

> Discover the essential role of the omarchy-settings Arch package. It provides the critical configuration files and defaults needed before main omarchy components can operate.

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

---

**The `omarchy-settings` Arch package serves as the static defaults bootstrap package that delivers all configuration files, system-wide defaults, and assets required before the main `omarchy` components can function properly.**

According to the [omac/o·marchy](https://github.com/omacom/omarchy) source code, `omarchy-settings` (and its development counterpart `omarchy-settings-dev`) is designed to separate immutable defaults from runtime logic. This architecture ensures that fresh installations and user accounts start with a consistent, working configuration while allowing the core `omarchy` package to focus on dynamic system management.

## How `omarchy-settings` Seeds New User Accounts

One of the primary responsibilities of `omarchy-settings` is populating `/etc/skel/` with the Omarchy configuration template.

When a new user account is created on an Arch system, files in `/etc/skel/` are automatically copied to that user's home directory. The `omarchy-settings` package pre-populates this directory so that any freshly created user instantly receives the complete Omarchy desktop environment configuration.

This seeding mechanism is documented in [`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md) at line 35, which describes how user-level defaults propagate through the system.

## Installing System-Wide Defaults

Beyond user templates, `omarchy-settings` installs configuration files across multiple system directories:

| Destination | Purpose |
|-------------|---------|
| `/etc/` | Core system configuration (e.g., `etc/fastfetch/config.jsonc` → `/etc/fastfetch/config.jsonc`) |
| `/usr/share/omarchy/default/` | Omarchy-specific default templates |
| `/usr/share/icons/` | Icon themes and assets |
| `/etc/snapper/config-templates/omarchy` | Btrfs snapshot configuration template |

As noted in [`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md) at line 86, these path mappings ensure that system utilities and desktop components find their configurations in standard locations without requiring manual setup.

## Providing Default systemd User Units

The package ships disabled systemd units that administrators can selectively enable. The most significant example is the backup infrastructure:

- **`omarchy-backup.timer`** — Ships disabled via the `omarchy-settings` PKGBUILD

This approach allows the backup subsystem to exist on all installations without automatically consuming resources. Administrators explicitly enable the timer when they want scheduled backups, as described in [`plans/backup.md`](https://github.com/omacom/omarchy/blob/main/plans/backup.md) at line 68.

## Packaging Static Assets

`omarchy-settings` bundles visual and interface resources under `/usr/share/omarchy/`:

- Omarchy icon font
- Distribution logos
- Theme resources

The logo assets entry at line 136 of [`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md) confirms that these resources install to standard XDG-compliant paths where GTK/Qt applications and display managers can locate them.

## Enabling ALPM Hook Integration

The `omarchy` package installs **pre-transaction hooks** specifically designed to watch for installs or upgrades of `omarchy-settings` or `omarchy-settings-dev`. These hooks ensure configuration files remain synchronized when the defaults package updates.

This hook mechanism is documented in [`docs/update-process.md`](https://github.com/omacom/omarchy/blob/main/docs/update-process.md) at line 101. The separation between `omarchy-settings` (static data) and `omarchy` (runtime logic with hooks) creates a clean update pipeline where configuration changes trigger appropriate system responses.

## Facilitating Configuration Re-Synchronization

When users run the `omarchy-reinstall-configs` command, the system forcibly copies the defaults that originated from `omarchy-settings` into the user's `$HOME` directory. This overwrites any divergent customizations, providing a "factory reset" mechanism for user configurations.

This capability relies on `omarchy-settings` remaining the canonical source of truth for default configurations.

## Installation and Usage Examples

```bash

# Install the stable Omarchy stack (includes omarchy-settings)

sudo pacman -S --needed omarchy omarchy-settings

```

```bash

# Install the development/edge stack (includes the dev variant)

sudo pacman -S --needed omarchy-dev omarchy-settings-dev

```

```bash

# After a system upgrade, force-reapply the default configs shipped by omarchy-settings

omarchy-reinstall-configs   # Resynchronises /etc/skel and $HOME defaults

```

## Key Source Files Defining `omarchy-settings` Architecture

- **[`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md)** — Complete mapping of `omarchy-settings` assets to destination paths
- **[`plans/backup.md`](https://github.com/omacom/omarchy/blob/main/plans/backup.md)** — Documentation of backup systemd units shipped via PKGBUILD
- **[`docs/update-process.md`](https://github.com/omacom/omarchy/blob/main/docs/update-process.md)** — ALPM hooks that react to `omarchy-settings` installs/upgrades
- **[`agents/skills/install-scripts.md`](https://github.com/omacom/omarchy/blob/main/agents/skills/install-scripts.md)** — Explanation of `/etc/skel` seeding used by `omarchy-finalize-user`
- **`test/shell.d/*`** — Test suites including [`update-available-test.sh`](https://github.com/omacom/omarchy/blob/main/update-available-test.sh) and [`update-file-conflict-test.sh`](https://github.com/omacom/omarchy/blob/main/update-file-conflict-test.sh) for verification

## Summary

- **`omarchy-settings`** is the static defaults bootstrap package that must install before `omarchy` runtime components
- Seeds `/etc/skel/` so new users receive complete Omarchy configurations automatically
- Installs system-wide defaults to `/etc/`, `/usr/share/omarchy/default/`, and standard XDG paths
- Ships disabled systemd units like `omarchy-backup.timer` for optional administrative features
- Bundles icon fonts, logos, and visual assets to `/usr/share/omarchy/`
- Triggers ALPM hooks in the `omarchy` package to maintain configuration synchronization
- Provides the canonical source for `omarchy-reinstall-configs` reset operations

## Frequently Asked Questions

### What is the difference between `omarchy-settings` and `omarchy-settings-dev`?

`omarchy-settings-dev` is the development/edge counterpart to the stable `omarchy-settings` package. It contains the same structural components but tracks the development branch of Omarchy, allowing testers and contributors to run bleeding-edge default configurations alongside `omarchy-dev`.

### Can I use Omarchy without installing `omarchy-settings`?

No. The `omarchy` package depends on `omarchy-settings` because it requires the seed files in `/etc/skel/`, system-wide defaults, and assets to function. Attempting to install `omarchy` without its settings package would leave the system without the necessary configuration foundation.

### What happens when `omarchy-settings` updates?

The pre-transaction hooks installed by the `omarchy` package detect the upgrade and execute synchronization logic. This ensures that any changes to default configurations propagate appropriately while preserving explicit user modifications where possible. For forced re-synchronization, run `omarchy-reinstall-configs`.

### Where does `omarchy-settings` store its files in the repository?

While the built package installs to system paths, the source repository organizes these files under standard directories that map to installation targets via the PKGBUILD. The complete mapping is documented in [`docs/file-layout.md`](https://github.com/omacom/omarchy/blob/main/docs/file-layout.md), showing how repository paths like `etc/fastfetch/config.jsonc` become `/etc/fastfetch/config.jsonc` on target systems.