How to Drop Packages Using `omarchy-pkg-drop` in Omarchy

omarchy-pkg-drop is a Pacman wrapper that safely removes packages—including virtual providers and orphaned dependencies—while automatically handling privilege escalation and idempotency.

The omarchy-pkg-drop utility is the standard mechanism for uninstalling software in the Omarchy ecosystem. Located at bin/omarchy-pkg-drop in the repository, this helper abstracts raw pacman calls to ensure consistent, migration-safe package removal across the entire codebase.

What Is omarchy-pkg-drop?

omarchy-pkg-drop is not merely an alias for pacman -R. According to the Omarchy source code, it is a dedicated wrapper that standardizes package removal semantics. When invoked, the script translates each supplied package name into a pacman -Rns --noconfirm operation, ensuring that both the target package and its orphaned dependencies are purged without interactive prompts. This design consolidates removal logic into a single executable used by migration scripts, feature-removal helpers, and test suites.

How It Works: Implementation Details

Automatic Privilege Escalation

The helper detects the current user’s privilege level. If the invoking user lacks root access, omarchy-pkg-drop automatically prefixes the operation with sudo. This eliminates manual privilege management in automation scripts and prevents "permission denied" errors during system migrations.

Virtual Package Resolution

When the requested name matches a virtual package (a meta-package that provides a capability rather than a concrete binary), the command resolves the underlying concrete providers before removal. For example, invoking the helper with a virtual package like voxtype-bin triggers resolution logic that identifies and removes the actual provider packages mapped to that virtual name.

Idempotent Execution

The implementation is designed to be idempotent. If a package specified in the argument list has already been removed from the system, omarchy-pkg-drop ignores the missing package and exits cleanly. This behavior makes the command safe to run repeatedly in idempotent system-setup routines and migration scripts without triggering "target not found" failures.

Usage Examples

Remove a single package:

omarchy-pkg-drop firefox

Remove multiple packages in one invocation:

omarchy-pkg-drop steam minecraft-launcher gnome-calculator

Explicitly use elevated privileges (the helper adds sudo automatically if omitted):

sudo omarchy-pkg-drop tailscale

Drop a virtual package, letting the helper resolve concrete providers:

omarchy-pkg-drop voxtype-bin

In shell scripts, use the helper to clean up development environments:

#!/usr/bin/env bash

# Example: Clean up PHP tooling

omarchy-pkg-drop php composer php-sqlite xdebug symfony-cli

Source Code Location and Testing

The core implementation resides in bin/omarchy-pkg-drop. The behavior is enforced by automated tests in test/shell.d/pkg-drop-test.sh, which verifies that the exact pacman command constructed by the helper matches the expected pacman -Rns --noconfirm signature.

Documentation governing its usage appears in AGENTS.md, which explains the relationship between omarchy-pkg-drop and other package-helper commands like omarchy-pkg-add. Real-world usage appears in migration scripts such as migrations/1788009111.sh, where obsolete packages are purged during system upgrades.

Summary

• omarchy-pkg-drop wraps pacman -Rns --noconfirm to standardize package removal.
• Automatic sudo: Detects root privileges and escalates only when necessary.
• Virtual package resolution: Expands meta-packages to concrete providers before removal.
• Idempotent: Safely ignores already-removed packages, making it ideal for automation.
• Source location: Implemented in bin/omarchy-pkg-drop and tested in test/shell.d/pkg-drop-test.sh.

Frequently Asked Questions

What is the difference between omarchy-pkg-drop and pacman -R?

omarchy-pkg-drop is a domain-specific wrapper that enforces Omarchy’s removal policy. While pacman -R removes only the specified package, omarchy-pkg-drop consistently applies the -Rns flags (removing dependencies and configuration files) and handles virtual package expansion, privilege escalation, and idempotent checks that raw pacman does not provide.

Does omarchy-pkg-drop handle dependencies?

Yes. The helper explicitly passes the -n and -s flags to pacman, which removes configuration files and unneeded dependencies (orphans) alongside the target package. This ensures the system remains clean after removal.

Where is omarchy-pkg-drop defined in the source code?

The executable script is located at bin/omarchy-pkg-drop in the Omarchy repository. Its behavior is documented in AGENTS.md and verified by the test suite in test/shell.d/pkg-drop-test.sh. Migration scripts such as migrations/1788009111.sh demonstrate production usage.

Is it safe to use omarchy-pkg-drop in automated scripts?

Yes. The command is explicitly designed for automation. It is idempotent (ignoring already-removed packages), handles privilege detection automatically, and standardizes error handling, making it safer than raw pacman calls in migration and provisioning scripts.

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