# Understanding the Difference Between Omarchy and Omarchy-Settings Packages > Learn the key differences between omarchy and omarchy-settings packages. Understand how omarchy-settings handles baseline configuration and omarchy manages runtime execution. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: deep-dive - Published: 2026-08-28 --- **The `omarchy-settings` package provides the static baseline configuration required before the runtime starts, while the `omarchy` package contains the executable runtime, CLI tools, and Quickshell desktop.** Omarchy is Basecamp's open-source Arch Linux development environment configuration. Understanding the **difference between omarchy and omarchy-settings packages** is essential for system administration and troubleshooting, as the codebase is deliberately split into two distinct Arch packages that enforce a strict separation between static configuration and executable runtime code. ## Architectural Separation: Code vs. Configuration As documented in [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md), the repository enforces a deliberate architectural boundary that mirrors the classic separation between configuration and code. ### omarchy-settings (Static Configuration Layer) The `omarchy-settings` package serves as the foundation that must be pre-installed before the runtime can initialize. According to the file layout documentation, this package ships: - Static defaults for the user's home directory under `/etc/skel` - Default systemd user units located in `/usr/lib/systemd/user/` - Configuration templates, fonts, and icons - Auxiliary scripts required for baseline environment setup The documentation explicitly states that `omarchy-settings` is installed when you run `omarchy-install` and provides the baseline configuration that the Omarchy runtime expects. ### omarchy (Runtime and CLI Layer) The `omarchy` package contains the active runtime components. It provides: - The Omarchy command-line interface (CLI) - The Quickshell QML desktop environment (`shell/`) - Theme handling and management utilities - Helper utilities and agent scripts located in `bin/` and `agents/` The runtime depends on `omarchy-settings` but does not bundle the static configuration files. This design ensures that user customizations in `~/.config` and `~/.local` remain isolated from runtime updates. ## Installation Sequence and Dependencies The installation process respects the dependency hierarchy between these packages. As outlined in [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md), the flow follows a strict order: 1. `omarchy-install` pulls the `omarchy-settings` package first to seed the required system files and skeleton directories. 2. Once baseline files are in place, the `omarchy` package is installed to provide the executable runtime. 3. The runtime can then start, reading its configuration from the files previously seeded by `omarchy-settings`. ## Independent Update Mechanisms The [`docs/update-process.md`](https://github.com/basecamp/omarchy/blob/main/docs/update-process.md) file explains how updates are handled separately for each package, ensuring that configuration changes and code changes do not interfere with each other. When a new version is released: - If only `omarchy` has a newer version, the runtime upgrades without touching static defaults, preventing unintentional overwriting of user customizations. - If `omarchy-settings` has a newer version, the update process replaces seeded configuration files (e.g., `/etc/skel/.config/…`, systemd user units) before or alongside the runtime upgrade. This separation allows configuration defaults to evolve without requiring a full runtime reinstall. The update checker implemented in `bin/omarchy-update-available` examines both package versions to determine which components require upgrading. ## Channel Management and Package Pairs Both packages are managed as synchronized pairs across distribution channels. The `bin/omarchy-channel-set` script switches between stable and development channels by manipulating both packages simultaneously to maintain version consistency. ```bash # Switch to the development channel (installs both dev packages) omarchy-channel-set dev # Verify which channel is currently active omarchy-channel-current ``` The system tracks the active channel by checking for the presence of either package pair (`omarchy`/`omarchy-settings` for stable, or `omarchy-dev`/`omarchy-settings-dev` for development) via the `bin/omarchy-channel-current` utility. ## Summary - **`omarchy-settings`** provides static baseline configuration, systemd units, and skeleton files that must exist in `/etc/skel` and system directories before the runtime initializes. - **`omarchy`** delivers the executable runtime, CLI tools, Quickshell desktop, and theme management utilities located in `bin/` and `shell/`. - The installation process always installs `omarchy-settings` before `omarchy` to satisfy the runtime's dependency on pre-installed configuration templates. - Updates are handled independently; runtime updates do not overwrite user configurations in `~/.config`, while settings updates refresh system-wide defaults. - Channel switching operates on both packages as a pair, ensuring that development or stable versions remain synchronized. ## Frequently Asked Questions ### Can I install omarchy without omarchy-settings? No. The `omarchy` package explicitly depends on `omarchy-settings` being installed first. The runtime expects the static configuration files, systemd units, and skeleton directory structures to exist in `/etc/skel` and `/usr/lib/systemd/user/` before it starts. Attempting to run the runtime without the settings package would result in missing configuration templates and failed service initialization. ### Will updating omarchy overwrite my personal configuration files? No. Because the runtime and static defaults are packaged separately, updating `omarchy` only upgrades the CLI tools and Quickshell desktop without touching files in your home directory. The `omarchy-settings` package manages system-wide defaults under `/etc/skel` and system directories, leaving your `~/.config` customizations intact unless you explicitly choose to refresh the settings package independently. ### How do I switch between stable and development channels? Use the `omarchy-channel-set` command followed by the desired channel name. Running `omarchy-channel-set dev` installs the development versions of both packages (`omarchy-dev` and `omarchy-settings-dev`), while `omarchy-channel-set stable` reverts to the standard releases. The `omarchy-channel-current` utility inspects which package pair is installed to report the active channel. ### What happens if omarchy-settings is updated but omarchy is not? When `omarchy-settings` receives an update without a corresponding `omarchy` update, the system refreshes the seeded configuration files, systemd units, and skeleton templates to their latest defaults. This allows the distribution to evolve baseline configurations and add new system services without requiring a full runtime upgrade, while the existing runtime continues to function with the updated defaults.