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

> Safely remove packages with omarchy-pkg-drop a Pacman wrapper that handles virtual providers orphaned dependencies and privilege escalation. Learn how to drop packages efficiently.

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

---

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

```bash
omarchy-pkg-drop firefox

```

Remove multiple packages in one invocation:

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

```

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

```bash
sudo omarchy-pkg-drop tailscale

```

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

```bash
omarchy-pkg-drop voxtype-bin

```

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

```bash
#!/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`](https://github.com/omacom/omarchy/blob/quattro/bin/omarchy-pkg-drop). The behavior is enforced by automated tests in [`test/shell.d/pkg-drop-test.sh`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/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`](https://github.com/omacom/omarchy/blob/main/AGENTS.md) and verified by the test suite in [`test/shell.d/pkg-drop-test.sh`](https://github.com/omacom/omarchy/blob/main/test/shell.d/pkg-drop-test.sh). Migration scripts such as [`migrations/1788009111.sh`](https://github.com/omacom/omarchy/blob/main/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.