Remove Packages

Soar provides straightforward commands for removing installed packages from your system. This guide covers the removal options, what happens during removal, and troubleshooting tips.

Usage

To remove a package, use the remove command or one of its aliases.

Removing a single package

remove

soar remove <package>

r

soar r <package>

del

soar del <package>

Example: remove 7z.

soar remove 7z

Command options

The remove command supports the following options.

Option	Description
--yes	Skip confirmation prompts. Automatically selects the first option when multiple packages match.
--all	Remove every installed variant of the named package, whatever family, repository or version it came from.

Using --yes

Skip interactive prompts when removing packages.

# Remove without confirmation
soar remove --yes 7z

# Automatically select first match when multiple variants exist
soar remove --yes bat

Using --all

Remove all installed variants of a package.

# Remove every installed variant of bat
soar remove --all bat

# Remove with --yes to skip bulk confirmation
soar remove --all --yes cat

Removes every variant

Using --all will remove ALL installed variants of the package, including those from different repositories and families. Use with caution.

Removing multiple packages

Remove multiple packages in a single command.

soar remove <package1> <package2> <package3>

Example: remove 7z and bat.

soar remove 7z bat

INFO

If you provide only the package name and several variants match, you will be prompted to select ONE package to remove. Use --all to remove all variants.

Removing a package installed from a URL

A package installed from a URL can be removed by that URL, which saves working out what it installed as:

soar remove https://github.com/owner/repo/releases/download/v1.2.3/tool-linux-x86_64.AppImage

This keeps working after the package has been updated, when the URL no longer matches the artifact currently installed.

Removing a package from a specific family

soar remove <family>/<package>

Example: remove rg as published by the ripgrep project.

soar remove ripgrep/rg

What Happens During Removal

When you remove a package, Soar performs these cleanup operations.

1. Pre-Remove Hook (if configured)
2. Binary Symlink Removal from ~/.local/share/soar/bin
3. Provides Symlink Cleanup for alternative names
4. Desktop Entry Removal from ~/.local/share/applications
5. Icon Symlink Cleanup from ~/.local/share/icons
6. Package Directory Removal from ~/.local/share/soar/packages
7. Cache Handling: download cache preserved (use soar clean --cache to reclaim)
8. Database Cleanup: removes the package record and portable entries

Example output:

Removed 7z#upstream.release:official (24.08)
  - Removed binary: ~/.local/share/soar/bin/7z
  - Removed directory: ~/.local/share/soar/packages/7z-24.08
  - Reclaimed 2.3 MiB

Partial vs Complete Removal

Complete removal

A complete removal occurs when:

• The package was successfully installed (is_installed = true)
• All files and symlinks are properly cleaned up
• The package is removed from the database

This is the normal and expected removal process.

Partial removal (broken packages)

A partial or incomplete installation can occur when:

• The installation process was interrupted (network failure, system crash)
• Disk space ran out during installation
• The package was manually deleted from the filesystem

These are marked as broken packages in Soar's database (is_installed = false).

Identifying broken packages

To check for broken or incomplete installations:

soar health

Example output showing broken packages:

Broken Packages (1):
  7z#upstream.release:official /home/user/.local/share/soar/packages/7z-24.08

Removing broken packages

To remove all broken packages:

soar clean --broken

This command:

• Lists all broken packages in the database
• Removes their directories (if they still exist)
• Removes any leftover symlinks
• Cleans up database entries

Troubleshooting

Stuck or incomplete removals

Check system health and fix broken symlinks.

soar health
soar clean --broken-symlinks

Package will not remove

Check file permissions, ensure the package is not running, and use verbose mode.

ls -la ~/.local/share/soar/packages/
pgrep -a <package>
soar --verbose remove <package>

For more help, see Health Check.

Manual cleanup

For manual cleanup of stuck packages:

1. Find the package directory.

   soar info | grep <package>

2. Remove the directory manually.

   rm -rf ~/.local/share/soar/packages/<package-directory>

3. Remove symlinks manually.

   rm -f ~/.local/share/soar/bin/<package>

4. Run a health check.

   soar health

5. Clean up any remaining broken symlinks.

   soar clean --broken-symlinks

Destructive commands

The rm -rf and rm -f commands above permanently delete files. Double-check each path before running them, since there is no undo.