Skip to content

Home

Jump to bottom
Jozef Gaal edited this page Aug 20, 2025 · 5 revisions

OrphyCleaner – Help & Documentation

📌 Overview

OrphyCleaner is a tool that scans your Linux system for orphaned or unused application folders and helps you decide whether to keep or remove them.
It provides descriptions of applications using multiple sources (Pacman, AUR, Flatpak) to make it easier to identify what a folder belongs to.

The app comes with a graphical interface where you can:

  • Browse detected application folders.
  • See descriptions of packages from system and community sources.
  • Open folders and delete them
  • Mark folders to keep so they won’t be suggested for removal again.
  • Save and restore your decisions between runs.

🔍 How scanning works

When you start the application:

  1. OrphyCleaner looks for application folders in common system and user locations, such as:
    • ~/.local/share/
    • Flatpak directories
    • AppImage folders
  2. It compares these against installed applications:
    • Pacman packages
    • AUR packages (via yay/paru, if available)
    • Flatpaks
    • AppImages
  3. Folders not matching installed apps are listed as candidates for cleanup.

📝 How descriptions are retrieved

When you select a folder in the interface:

  1. OrphyCleaner tries to guess a package name from the folder name.
  2. It queries, in order:
    • Pacman (pacman -Si)
    • AUR helper (yay or paru, -Si)
    • Flatpak (flatpak info)
  3. The first valid description found is displayed.
  4. If no description is found, the app shows “Description not found”.

💾 Files used and saved

OrphyCleaner stores some information locally:

  • ~/.cache/orphycleaner/orphycleaner_pkg_cache.json

    • Cache of package descriptions.
    • Prevents repeated lookups for the same package/folder.
    • Keys are prefixed with their source, e.g. pacman:pkgname, aur:pkgname, or flatpak:pkgname.
    • To clear the cache, simply delete this file.

  • ~/.local/share/orphycleaner/kept_folders.txt

    • List of folders marked as kept.
    • Prevents OrphyCleaner from suggesting them for cleanup again.
    • You can edit or delete this file manually if needed.

⚙️ Caching and negative results

  • If a package is not found in Pacman, AUR, or Flatpak, OrphyCleaner saves a placeholder ("<not found>" or "Description not found") in the cache.
  • This avoids repeated long lookups for missing packages.
  • To force a fresh check (e.g. if the package later becomes available), delete ~/.cache/orphycleaner/orphycleaner_pkg_cache.json.

🗑️ Cleaning workflow

  1. Browse through detected folders.
  2. Read the description to decide whether it belongs to an installed application.
  3. If you want to keep it, mark it as kept (this updates kept_folders.txt).
  4. If you don’t want it, you can directly remove it or manually outside the app.

❓ FAQ

Q: Why does description lookup take a few seconds sometimes?
Because queries to AUR helpers or Flatpak info require system calls or network requests. To speed things up, OrphyCleaner caches results.

Q: I see “Description not found”, but I know the package exists!
Make sure yay/paru (for AUR) or Flatpak is installed and available in your PATH. If it still fails, try deleting the cache file.

Q: What if I don’t want OrphyCleaner to remember my choices?
Delete both:

  • ~/.cache/orphycleaner/orphycleaner_pkg_cache.json
  • ~/.local/share/orphycleaner/kept_folders.txt

Clone this wiki locally