# How Omarchy Seeds New User Environments Using `/etc/skel`

> Discover how Omarchy leverages /etc/skel to seed new user environments with essential dotfiles and configurations for a seamless setup.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: how-to-guide
- Published: 2026-08-20

---

**Omarchy uses the standard Unix skeleton directory mechanism via `/etc/skel` to populate new user home directories with default dotfiles, configurations, and theme assets when accounts are created.**

The Omarchy desktop environment implements a three-phase provisioning model that starts with static file seeding through `/etc/skel`. This approach ensures every new user begins with a consistent, preconfigured environment derived directly from the `omarchy-settings` package.

## The Three-Phase User Provisioning Model

Omarchy divides environment setup into distinct phases: **Seed**, **Finalize**, and **Resync**. Each phase addresses different constraints in Unix user management.

| Phase | Purpose | Trigger |
|-------|---------|---------|
| **Seed** | Copy static defaults into new home directories | User creation via `useradd -m` |
| **Finalize** | Execute runtime-dependent configuration | First user login |
| **Resync** | Restore original defaults for existing users | Manual invocation |

Only the Seed phase modifies `/etc/skel` directly. The other phases operate after the initial home directory exists.

## How the Seed Phase Works in `/etc/skel`

The `omarchy-settings` package installs a complete file tree under `/etc/skel/` based on a build-time mapping defined in [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md). When Arch Linux's `useradd` runs with the `-m` (create home) flag, it automatically copies this entire tree to the new user's `$HOME`.

Key mappings from the Omarchy source:

- `config/**` → `/etc/skel/.config/**` — default application configurations
- `applications/*.desktop` → `/etc/skel/.local/share/applications/` — desktop entry files
- `default/bashrc` → `/etc/skel/.bashrc` — baseline shell initialization

This implementation lives in the Omarchy repository at `basecamp/omarchy`, specifically documented in the [Seed section of file-layout.md](https://github.com/basecamp/omarchy/blob/quattro/docs/file-layout.md#L35-L43).

### Creating a New User

The system installer and administrative tools use standard Linux commands:

```bash
sudo useradd -m alice

```

After execution, `/home/alice` contains the exact file tree from `/etc/skel/`, including all dotfiles and directory structures shipped by `omarchy-settings`.

## The Finalize Phase: What `/etc/skel` Cannot Do

Static files in `/etc/skel` cannot handle dynamic content: path expansion, hardware detection, or user-specific symlinks. Omarchy addresses this with `omarchy-provision-user`, which runs automatically on first login.

This script, located at `bin/omarchy-provision-user` in the repository, performs actions such as:

- Expanding `$OMARCHY_PATH` variables in configuration files
- Creating skill-based symlinks that depend on installed packages
- Setting MIME type associations based on available applications

Separate from the initial seed, Finalize ensures the environment adapts to actual runtime conditions without polluting `/etc/skel` with template variables.

## The Resync Phase: Restoring Defaults for Existing Users

Because `/etc/skel` is only consulted at account creation, existing users do not automatically receive updated defaults when `omarchy-settings` changes. The `omarchy-reinstall-configs` command provides an explicit reset mechanism.

From `bin/omarchy-reinstall-configs` (lines 14-20):

```bash
#!/bin/bash

# Force-reinstall all skel defaults, overwriting current user configs

cp -af /etc/skel/. ~/

```

Run this as the target user:

```bash
omarchy-reinstall-configs

```

This destructively restores the original seed state, useful for troubleshooting or adopting breaking configuration changes.

## Key Source Files and Their Roles

| File Path | Responsibility |
|-----------|---------------|
| [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md) | Documents the three-phase model and build-time file mappings |
| `bin/omarchy-reinstall-configs` | Implements resync via `cp -af /etc/skel/. ~/` |
| `bin/omarchy-provision-user` | Performs per-user finalization after skel copy |
| `default/bashrc` | Source for `/etc/skel/.bashrc` |
| `config/**` | Default user configurations installed under `/etc/skel/.config` |

## Design Implications of the `/etc/skel` Approach

Omarchy's reliance on standard Unix mechanisms provides several advantages:

- **Predictability**: New users receive identical starting states regardless of installation timing
- **Tool compatibility**: Works with any user creation tool that respects `useradd` conventions
- **Clear upgrade path**: Separates immutable defaults (skel) from mutable user data
- **Explicit reset**: The resync command makes configuration recovery intentional rather than automatic

The trade-off is that existing users must consciously opt into configuration updates via `omarchy-reinstall-configs`, preventing unexpected disruption of customized environments.

## Summary

- **`/etc/skel`** in Omarchy contains the complete default user environment shipped by `omarchy-settings`
- **New users** receive these files automatically via `useradd -m` during account creation
- **`omarchy-provision-user`** handles dynamic configuration that static files cannot express
- **`omarchy-reinstall-configs`** allows existing users to restore original defaults when needed
- The build-time mapping in [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md) explicitly defines which source files populate `/etc/skel`

## Frequently Asked Questions

### What files does Omarchy put in `/etc/skel`?

The `omarchy-settings` package installs dotfiles, XDG configuration directories, desktop application entries, and theme assets. Specific mappings include `config/**` to `.config/`, `applications/*.desktop` to `.local/share/applications/`, and `default/bashrc` to `.bashrc`. The complete list is documented in [`docs/file-layout.md`](https://github.com/basecamp/omarchy/blob/main/docs/file-layout.md).

### Why doesn't `/etc/skel` update existing user homes?

The Unix `useradd` mechanism only copies `/etc/skel` at account creation time. This is by design: modifying existing home directories would destroy user customizations. Omarchy respects this boundary and provides `omarchy-reinstall-configs` as an explicit, user-initiated reset path.

### What happens if I run `omarchy-reinstall-configs`?

The command executes `cp -af /etc/skel/. ~/` which forcibly overwrites all files in your home directory with the current contents of `/etc/skel`. This destroys any personal modifications to files that exist in the skeleton tree. Run it only when you intend to restore factory defaults.

### How does Omarchy handle machine-specific configuration that `/etc/skel` cannot contain?

The `omarchy-provision-user` script runs once per user on first login to handle dynamic elements: expanding environment variables, detecting hardware capabilities, and creating conditional symlinks. This separates static templates from runtime-adaptive configuration.