# What Does the Omarchy-Settings Package Include? A Complete Component Guide > Explore the omarchy-settings package! Discover configuration files, theme definitions, menu schemas, Quickshell UI, migrations, and CLI tools for managing your Omarchy desktop environment. - Repository: [37signals/omarchy](https://github.com/basecamp/omarchy) - Tags: component-guide - Published: 2026-08-22 --- **The omarchy-settings package bundles default configuration files, theme definitions, menu schemas, Quickshell UI definitions, migration scripts, and CLI utilities that initialize and manage the Omarchy desktop environment.** The **omarchy-settings** package is the foundational configuration layer for Omarchy, the declarative desktop environment developed by Basecamp. It resides in the `basecamp/omarchy` repository and provides the static assets and runtime definitions that the shell, compositor, and user tooling consume at startup. ## Core Configuration Components ### Default Dotfiles and Compositor Configs At the heart of the package are the baseline configuration templates stored in `config/`. These files define the out-of-the-box behavior for Hyprland, tmux, zsh, and other tools. When a user runs `omarchy-refresh-config`, the system copies files such as [`config/hypr/hyprland.lua`](https://github.com/basecamp/omarchy/blob/main/config/hypr/hyprland.lua) into `~/.config`, establishing the default window manager rules, keybindings, and startup applications. ### Theme Definitions and Color Palettes Visual consistency is enforced through `themes/*/colors.toml`, which defines color palettes, accent values, and theme-specific styling parameters. These TOML files feed into the theming engine, allowing the `omarchy-theme-switcher` command to apply global color changes across the desktop environment. ## User Interface Definitions ### Menu Schemas The desktop menu structure is declared in `default/omarchy/omarchy-menu.jsonc`. This JSONC file specifies icons, application groups, and command shortcuts that populate the Omarchy launcher. The schema supports comments and is parsed at runtime to generate the navigable menu hierarchy. ### Quickshell UI Layout The visual shell itself is defined by `shell/shell.qml`, a QML file that renders panels, pop-ups, and on-screen displays (OSDs). This file interfaces with the settings package to load theme data and configuration state, presenting the unified desktop interface. ## Operational Scripts and Utilities ### Migration Scripts Versioned upgrade paths live in `migrations/*.sh`. These shell scripts automate configuration transitions between Omarchy releases, ensuring that user customizations remain compatible with new defaults. Each migration is timestamped and executed sequentially during the update process. ### CLI Convenience Tools The `bin/` directory contains executable helpers like `omarchy-update-status` and `omarchy-theme-switcher`. These binaries read settings from the package and expose them as command-line interfaces, bridging the gap between static configuration files and runtime user interaction. ## Validation and Documentation ### Test Suite Configuration integrity is verified by `test/shell.d/*-test.sh`. These shell-test scripts validate that settings parse correctly, that migrations succeed without error, and that theme applications produce expected color values. ### Human-Readable Guides Documentation such as [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md) explains the organization of the settings package, providing developers and advanced users with reference material for extending or debugging the configuration. ## Code Examples Refresh the user’s configuration with the defaults from the omarchy-settings package: ```bash omarchy-refresh-config hypr/hyprland.lua ``` Switch to the "dark" theme defined in the package: ```bash omarchy-theme-switcher dark ``` List all menu entries that originate from the settings package: ```bash jq '.menu[] | select(.source=="omarchy-settings")' \ "$OMARCHY_PATH/default/omarchy/omarchy-menu.jsonc" ``` Execute a specific migration script manually (rarely required): ```bash bash "$OMARCHY_PATH/migrations/1787133200.sh" ``` ## Summary - The **omarchy-settings package** supplies the baseline `~/.config` files for Hyprland, tmux, and zsh via the `config/` directory. - **Theme definitions** in `themes/*/colors.toml` drive global visual styling accessible through `omarchy-theme-switcher`. - The **menu schema** in `default/omarchy/omarchy-menu.jsonc` and the **Quickshell UI** in `shell/shell.qml` define the user interface layer. - **Migration scripts** in `migrations/*.sh` ensure seamless upgrades between Omarchy versions. - **CLI utilities** in `bin/omarchy-*` provide command-line access to configuration state. - Comprehensive **testing** in `test/shell.d/` and **documentation** in `docs/` guarantee reliability and clarity. ## Frequently Asked Questions ### What is the primary function of the omarchy-settings package? The package serves as the single source of truth for Omarchy's default configuration state. It bundles static files, schemas, and scripts that initialize the desktop environment, manage theming, and handle versioned configuration migrations. ### Where are the default Hyprland configurations stored? Default compositor settings reside in [`config/hypr/hyprland.lua`](https://github.com/basecamp/omarchy/blob/main/config/hypr/hyprland.lua) within the package. The `omarchy-refresh-config` command copies this file into the user's home directory to establish baseline window management rules. ### How does Omarchy handle configuration updates? Versioned shell scripts located in `migrations/*.sh` execute sequentially during updates. These scripts transform existing user configurations to match new package defaults without overwriting customizations. ### Can I run the migration scripts manually? Yes. While the update process runs these automatically, you can execute a specific migration directly using `bash "$OMARCHY_PATH/migrations/[timestamp].sh"` for troubleshooting or forced re-application.