# How to Install Optional Software with Omarchy: The Complete Guide

> Easily install optional software with Omarchy using the omarchy install command. Manage packages without pacman or yay privileges. Get the complete guide now.

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

---

**Use the `omarchy install` command followed by bundle names to install optional software packages without manually managing pacman or yay privileges.**

The **Omarchy** distribution provides a streamlined wrapper for managing optional software through bundle-based installations. Instead of interacting directly with Arch Linux package managers, you use the high-level `omarchy install` command which handles privilege escalation, package resolution, and dependency management automatically. This approach ensures consistent system state while simplifying the installation of development tools, gaming platforms, and containerization software.

## Understanding the Omarchy Install Command

The `omarchy install` command serves as the primary interface for adding optional software to your system. Defined in the **Skill definition file** at [`default/agents/skills/omarchy/SKILL.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/SKILL.md), this command belongs to the install command group and maps user-friendly bundle names to concrete Arch Linux or AUR packages.

When you invoke the command, Omarchy performs three distinct operations:

1. Resolves the requested bundle name against internal package lists
2. Maps each bundle to specific packages defined in repository files
3. Executes the appropriate helper script with correct privileges

The system differentiates between standard repository packages and AUR-only software, routing each to `omarchy-pkg-add` or `omarchy-pkg-aur-add` respectively.

## Discovering Available Optional Bundles

Before installing, you can view which optional bundles are available on your system. Omarchy maintains these definitions in `install/omarchy-other.packages`, separate from the core packages listed in `install/omarchy-base.packages`.

To list available install commands and bundles:

```bash
omarchy commands --json | jq -r '.[] | select(.group=="install") | .summary'

```

For a more direct view of bundle contents:

```bash
omarchy install --list

```

This outputs mappings such as `docker` (containing `docker` and `docker-compose`) or `games` (including `steam`, `lutris`, and `wine`).

## Installing Optional Software Bundles

Install one or more bundles by passing their names as arguments to the `omarchy install` command. The wrapper handles privilege escalation automatically through [`install/helpers/as-root.sh`](https://github.com/omacom/omarchy/blob/main/install/helpers/as-root.sh), eliminating the need for manual `sudo` or `pkexec` calls.

To install Docker and development tools:

```bash
omarchy install docker dev-tools

```

The command reads the bundle definitions from `omarchy-other.packages`, filters comments and empty lines, and feeds the resulting package list to the underlying package manager.

### Installing AUR-Only Packages

Some bundles contain packages exclusive to the Arch User Repository. For these, Omarchy automatically invokes `omarchy-pkg-aur-add` instead of the standard helper. For example, installing the 1Password beta:

```bash
omarchy install 1password-beta

```

### Viewing Bundle Contents

To inspect which packages a bundle contains before installing:

```bash
omarchy install --show docker

```

This reads directly from the package list files without executing any installation steps.

## How the Installation Process Works

Under the hood, the installation follows a precise execution path through several key files in the Omarchy repository:

1. **Command Definition**: [`default/agents/skills/omarchy/SKILL.md`](https://github.com/omacom/omarchy/blob/main/default/agents/skills/omarchy/SKILL.md) defines the install command entry and its usage parameters (lines 45-46 in the Command Groups table)

2. **Package Lists**: The system references `install/omarchy-other.packages` for optional software and `install/omarchy-base.packages` for core components

3. **Privilege Handling**: The helper script at [`install/helpers/as-root.sh`](https://github.com/omacom/omarchy/blob/main/install/helpers/as-root.sh) wraps all `pacman` and `yay` calls, managing sudo escalation safely

4. **Execution**: Based on package origin, the system calls either `omarchy-pkg-add` (official repos) or `omarchy-pkg-aur-add` (AUR packages)

This architecture ensures that privilege escalation happens consistently through a single trusted path, rather than requiring users to manually invoke administrative commands.

## Advanced Installation Options

Omarchy provides additional flags for managing edge cases and custom configurations.

### Force Reinstallation

If a previous installation attempt failed partially, force a clean reinstall:

```bash
omarchy install --force docker

```

### Custom Bundles

You can define custom bundles by editing `install/omarchy-other.packages` to add new bundle definitions. After modifying the file, install your custom bundle using the standard syntax:

```bash
omarchy install my-custom-bundle

```

### Verification

To verify installed optional bundles:

```bash
omarchy install --list-installed

```

Alternatively, query the package manager directly:

```bash
pacman -Qq | grep -E '^docker|steam|nodejs'

```

## Summary

- Use **`omarchy install <bundle>`** to add optional software without manual privilege management
- Bundle definitions reside in **`install/omarchy-other.packages`** while core packages use **`install/omarchy-base.packages`**
- The system automatically routes packages to **`omarchy-pkg-add`** or **`omarchy-pkg-aur-add`** based on repository origin
- Privilege escalation is handled securely through **[`install/helpers/as-root.sh`](https://github.com/omacom/omarchy/blob/main/install/helpers/as-root.sh)**
- Inspect bundle contents with **`--show`**, force reinstalls with **`--force`**, and list installed bundles with **`--list-installed`**

## Frequently Asked Questions

### What is the difference between omarchy-base.packages and omarchy-other.packages?

The **`omarchy-base.packages`** file contains mandatory core packages required for the Omarchy distribution to function, while **`omarchy-other.packages`** defines optional bundles that users can selectively install. The install command specifically targets the optional package list when resolving bundle names.

### Do I need to use sudo with omarchy install?

No. The **`omarchy install`** command handles privilege escalation automatically through the **[`as-root.sh`](https://github.com/omacom/omarchy/blob/main/as-root.sh)** helper script. You should run the command as your regular user; the wrapper will invoke `sudo` or `pkexec` internally when calling `omarchy-pkg-add` or `omarchy-pkg-aur-add` to interact with the package manager.

### Can I install multiple bundles at once?

Yes. Pass multiple bundle names as space-separated arguments: **`omarchy install docker dev-tools games`**. The command resolves each bundle from **`omarchy-other.packages`** and installs all corresponding packages in a single operation, handling dependencies across bundles intelligently.

### How do I see what packages are included in a bundle before installing?

Use the **`--show`** flag followed by the bundle name: **`omarchy install --show dev-tools`**. This displays the specific package names defined in the package list files without triggering an actual installation, allowing you to verify bundle contents beforehand.