# Where Are Omarchy Configuration Files Located? A Complete Directory Guide

> Find omarchy configuration files easily. Discover their locations in the config directory, user home, and application-specific paths for seamless customization.

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

---

**Omarchy stores all user-editable configuration files in the `config/` directory at the repository root, which during installation are copied to `$HOME/.config/omarchy` and application-specific locations such as `~/.config/hypr/` and `~/.config/kitty/`.**

Omarchy is an open-source desktop environment that maintains a flat, predictable hierarchy for its configuration assets. Understanding where **Omarchy configuration files** reside enables you to customize everything from the Hyprland compositor to terminal emulators and shell prompts using the `omarchy-refresh-config` command.

## Repository Configuration Directory Structure

All default configuration templates live in the **`config/`** directory at the repository root. This structure mirrors the runtime layout used after installation, making it straightforward to locate specific settings.

### The Root config/ Folder

The `config/` directory contains subdirectories for each integrated tool and service. During the installation process, files from this hierarchy are copied to the user's home configuration tree. The flat structure ensures that every Omarchy configuration file is discoverable without nested complexity.

## User Configuration Locations

After installation, Omarchy populates two primary locations on your system:

- **`$HOME/.config/omarchy`** – Core Omarchy settings and hook scripts
- **Application-specific directories** – Tool configurations copied to standard XDG paths like `~/.config/hypr/`, `~/.config/kitty/`, and `~/.config/tmux/`

When you run `omarchy-refresh-config <path>`, the system copies the corresponding file from `$OMARCHY_PATH/config/<path>` to your user configuration directory while preserving backups of existing files.

## Core Configuration Directories Explained

### config/omarchy (Core Settings)

The **`config/omarchy/`** subdirectory contains the central Omarchy configuration, including [`shell.json`](https://github.com/omacom/omarchy/blob/main/shell.json) which defines the application menu, launcher behavior, and global settings. The **`config/omarchy/hooks/`** directory provides optional user-hooks that execute at specific lifecycle points, such as pre-refresh or post-update events. Example templates include `post-update.d/show-update-notification.sample`.

### config/hypr (Window Compositor)

Hyprland configuration resides in **`config/hypr/`**, primarily within [`hyprland.lua`](https://github.com/omacom/omarchy/blob/main/hyprland.lua). This file defines monitor layouts, keybindings, window rules, and compositor behavior. Refreshing this configuration directly updates your desktop environment's window management.

### Terminal Emulator Configurations

Omarchy supports multiple terminal emulators through dedicated configuration directories:

- **`config/kitty/`** – Contains [`kitty.conf`](https://github.com/omacom/omarchy/blob/main/kitty.conf) for the Kitty terminal emulator
- **`config/foot/`** – Contains [`foot.ini`](https://github.com/omacom/omarchy/blob/main/foot.ini) for the Foot terminal
- **`config/xdg-terminal-exec/`** – Contains `hyprland-xdg-terminals.list` defining fallback terminal priorities

### Tool-Specific Configurations

Additional tooling configurations include:

- **`config/tmux/`** – [`tmux.conf`](https://github.com/omacom/omarchy/blob/main/tmux.conf) session manager settings
- **[`config/starship.toml`](https://github.com/omacom/omarchy/blob/main/config/starship.toml)** – Starship prompt theme and formatting
- **`config/opencode/`** – [`opencode.json`](https://github.com/omacom/omarchy/blob/main/opencode.json) for Opencode tooling integration
- **`config/obsidian/`** – [`user-flags.conf`](https://github.com/omacom/omarchy/blob/main/user-flags.conf) for Obsidian markdown editor flags
- **`config/btop/`** – [`btop.conf`](https://github.com/omacom/omarchy/blob/main/btop.conf) system monitor configuration

## How to Refresh Configuration Changes

After editing any file in the repository's `config/` directory, you must refresh it to apply changes to your active environment. The **`omarchy-refresh-config`** command handles this synchronization while backing up existing user configurations.

Refresh specific configuration files using these commands:

```bash

# Refresh the core Omarchy shell configuration

omarchy-refresh-config omarchy/shell.json

# Refresh the Hyprland compositor configuration

omarchy-refresh-config hypr/hyprland.lua

# Refresh the Kitty terminal configuration

omarchy-refresh-config kitty/kitty.conf

```

To list all available configuration templates and edit them before refreshing:

```bash

# List all available Omarchy config files

omarchy list-config

# Edit a specific config file in your editor and apply it

$EDITOR $OMARCHY_PATH/config/omarchy/shell.json
omarchy-refresh-config omarchy/shell.json

```

## Key Configuration Files Reference

These critical files control major Omarchy subsystems:

- **[`config/omarchy/shell.json`](https://github.com/omacom/omarchy/blob/main/config/omarchy/shell.json)** – Defines the Omarchy menu, launcher, and global desktop settings
- **`config/omarchy/hooks/*`** – Executable scripts triggered before/after refreshes or updates
- **[`config/hypr/hyprland.lua`](https://github.com/omacom/omarchy/blob/main/config/hypr/hyprland.lua)** – Hyprland layout, keybindings, and monitor definitions
- **[`config/starship.toml`](https://github.com/omacom/omarchy/blob/main/config/starship.toml)** – Cross-shell prompt customization
- **[`config/tmux/tmux.conf`](https://github.com/omacom/omarchy/blob/main/config/tmux/tmux.conf)** – Terminal session management and layout

## Summary

- Omarchy configuration files reside in the **`config/`** directory at the repository root
- User copies are stored in **`$HOME/.config/omarchy`** and tool-specific XDG directories
- Use **`omarchy-refresh-config <path>`** to apply changes from repository defaults to your live system
- The **`config/omarchy/`** subdirectory contains core settings and hook scripts
- Window compositor settings are in **[`config/hypr/hyprland.lua`](https://github.com/omacom/omarchy/blob/main/config/hypr/hyprland.lua)**
- Terminal configurations are separated into **`config/kitty/`**, **`config/foot/`**, and related directories

## Frequently Asked Questions

### Where does Omarchy store configuration files after installation?

After installation, Omarchy copies configuration files from the repository's `config/` directory to `$HOME/.config/omarchy` for core settings and to application-specific XDG directories (such as `~/.config/hypr/` and `~/.config/kitty/`) for tool-specific configurations. The original repository files serve as templates that can be refreshed back into the user directories using the `omarchy-refresh-config` command.

### How do I apply changes to Omarchy configuration files?

Run the **`omarchy-refresh-config <path>`** command where `<path>` is the relative path within the `config/` directory. For example, `omarchy-refresh-config omarchy/shell.json` copies the updated shell configuration from the repository to your user directory while preserving a backup of your previous settings. This ensures that edits to repository templates safely propagate to your active desktop environment.

### What is the difference between the repository config/ directory and ~/.config/omarchy?

The repository's **`config/`** directory contains the default, version-controlled templates maintained by the Omarchy project. The **`~/.config/omarchy/`** directory contains your live, user-specific configurations that the system actually reads. The `omarchy-refresh-config` command bridges these two locations by copying from the repository defaults to your user directory, allowing you to customize settings while retaining the ability to reset to known good defaults.

### Can I create custom hooks in Omarchy?

Yes, the **`config/omarchy/hooks/`** directory supports user-defined scripts that execute at specific lifecycle points. Place executable scripts in subdirectories like `post-update.d/` or `pre-refresh.d/` within your user configuration. These hooks run automatically during the corresponding Omarchy operations, enabling custom notifications, backup routines, or environment adjustments whenever configurations are refreshed or the system is updated.