How to Install Optional Software with Omarchy: The Complete Guide

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, 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:

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

For a more direct view of bundle contents:

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, eliminating the need for manual sudo or pkexec calls.

To install Docker and development tools:

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:

omarchy install 1password-beta

Viewing Bundle Contents

To inspect which packages a bundle contains before installing:

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 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 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:

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:

omarchy install my-custom-bundle

Verification

To verify installed optional bundles:

omarchy install --list-installed

Alternatively, query the package manager directly:

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
• 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 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.

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