What Is the omarchy-settings Package in Omarchy? Purpose and Implementation

The omarchy-settings package is an Arch Linux package that bundles static assets, default user configurations, and resource templates for Omarchy, enabling independent updates and safe default refreshes via the omarchy-refresh-config utility.

The omarchy-settings package serves as the static content layer for the Omarchy ecosystem, separating immutable defaults from the core application logic. As an independent Arch Linux package, it ships everything from Hyprland configurations to Snapper templates without bloating the main binary distribution. This architecture allows Omarchy to deliver updated defaults and visual assets to users without requiring a full system upgrade or risking configuration drift.

Core Responsibilities of the omarchy-settings Package

Default Configuration Delivery

The primary role of omarchy-settings is to provide baseline configuration files that populate a user’s home directory. All default configs reside under $OMARCHY_PATH/config/ within the package structure. The omarchy-refresh-config helper (located at bin/omarchy-refresh-config) copies these files to ~/.config/ when initializing or resetting user environments.

According to the repository’s test suite, the refresh command validates that it can copy defaults from the package to user directories, ensuring that new installations receive consistent starting configurations for components like Hyprland, Waybar, and terminal emulators.

Static Asset Bundling

Beyond text configurations, the package ships static resources that remain immutable at runtime. This includes icon sets, custom fonts, and Snapper configuration templates. The repository’s Snapper verification test (test/shell.d/snapper-test.sh at lines 114–116) confirms that installing omarchy-settings places a template at /etc/snapper/config-templates/omarchy, which the system uses for filesystem snapshot management.

These assets are referenced by QML components and CLI tools throughout Omarchy, but they are managed centrally through this package to ensure visual and behavioral consistency across updates.

Independent Versioning and Updates

By packaging settings separately from the core Omarchy binaries, the system achieves separate versioning. The update checker explicitly includes omarchy-settings (and its development variant) when scanning for available updates, as demonstrated in test/shell.d/update-available-test.sh at lines 125–137.

This separation means users can receive new default configurations, themes, or policy templates without downloading a new build of the core application. It also supports the omarchy-settings-dev package, which mirrors the stable version but tracks the development branch, allowing testers to preview new defaults without affecting production installations.

Migration Support

The package serves as a canonical source for migration scripts. When Omarchy needs to relocate files or update directory structures, migration logic references the installed settings package to locate original default files. The test at test/shell.d/unowned-system-paths-test.sh (lines 35–38) illustrates how the system queries the package to determine which files should be copied or moved during path migrations, ensuring that system updates do not orphan user configurations.

Technical Implementation and File Locations

Package Detection and Build Integration

The Omarchy build system detects the settings package through PKGBUILD inspection. In test/shell.d/config-test.sh (lines 131–135), the test suite verifies that both omarchy-settings and omarchy-settings-dev are properly identified during the build process, ensuring that the correct static assets are bundled into the final installation media.

The omarchy-refresh-config Mechanism

The omarchy-refresh-config utility materializes the package’s defaults into the user environment. When invoked with a specific path argument, it copies the corresponding file from $OMARCHY_PATH/config/ to ~/.config/, preserving directory structure and permissions.

Working with omarchy-settings in Practice

Installing the Package

You can install the settings package through the standard Omarchy update mechanism or directly via pacman:

# Automatic installation via Omarchy's update script

omarchy-update

# Manual installation

sudo pacman -S omarchy-settings

Refreshing Default Configurations

To reset or initialize a specific configuration file from the package defaults:

# Copies $OMARCHY_PATH/config/hypr/hyprland.lua to ~/.config/hypr/hyprland.lua

omarchy-refresh-config hypr/hyprland.lua

Accessing Stored Settings

User-specific state data derived from package defaults is stored in ~/.local/state/omarchy/settings/. For example, to read a weather location setting:

jq -r .name ~/.local/state/omarchy/settings/weather.json

# Output: "Malibu"

Utilizing Snapper Templates

After installation, the package-provided Snapper template is available at the system level:

cat /etc/snapper/config-templates/omarchy

Summary

• The omarchy-settings package is the dedicated Arch Linux package for Omarchy’s static content and default configurations.
• It separates immutable assets (icons, fonts, templates) and default configs from the core application, enabling independent versioning.
• The omarchy-refresh-config helper copies files from $OMARCHY_PATH/config/ to user home directories.
• The package includes Snapper templates verified at test/shell.d/snapper-test.sh and is explicitly tracked by the update checker at test/shell.d/update-available-test.sh.
• A development variant (omarchy-settings-dev) allows testing new defaults without destabilizing production systems.
• Migration scripts reference the package as a canonical source for file locations during system updates.

Frequently Asked Questions

What files does the omarchy-settings package actually install?

The package installs static configuration templates under $OMARCHY_PATH/config/, Snapper templates at /etc/snapper/config-templates/omarchy, and visual assets including icons and fonts. These files serve as the source for the omarchy-refresh-config utility when populating user home directories.

How can I update default configurations without reinstalling the entire Omarchy core?

Run omarchy-update or sudo pacman -S omarchy-settings to fetch the latest settings package. Because the update checker explicitly includes omarchy-settings in its scan (as shown in test/shell.d/update-available-test.sh), you receive new defaults independently of core binary updates. Then use omarchy-refresh-config <path> to materialize specific updated files into your ~/.config/ directory.

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

omarchy-settings tracks the stable release branch and ships production-ready defaults. omarchy-settings-dev mirrors this structure but sources from the development branch, allowing developers and early adopters to test new configuration schemas, themes, or policy templates before they reach stable releases.

How does Omarchy handle configuration migrations using this package?

Migration scripts query the installed omarchy-settings package to locate canonical default files when moving or copying user data during system updates. As illustrated in test/shell.d/unowned-system-paths-test.sh (lines 35–38), the system references the package structure to determine which files require migration, ensuring that user modifications are preserved while updating the underlying defaults.

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