Skip to main content

Orphan Scan

Finds and removes files in your download directories that aren't associated with any torrent.

How It Works​

  1. Scan roots are determined dynamically - qui scans all unique SavePath directories from your current torrents, not qBittorrent's default download directory
  2. Files not referenced by any torrent are flagged as orphans
  3. You preview the list before confirming deletion
  4. Empty directories are cleaned up after file deletion
note

qui normalizes Unicode paths to canonical NFC form during matching. This avoids false orphans when equivalent composed/decomposed names are reported differently. On normalization-sensitive filesystems, two byte-distinct canonical-equivalent names are treated as one logical path.

info

If you have multiple active qBittorrent instances with Has local filesystem access enabled, and their torrent SavePath directories overlap, qui also protects files referenced by torrents from those other instances (even when scanning a single instance).

To do this safely, qui must be able to determine whether scan roots overlap. If any other local-access instance is unreachable/not ready, the scan fails to avoid false positives.

warning

Disabled instances are not protected. If you have a disabled instance with local filesystem access that shares save paths with an active instance, its files may be flagged as orphans. Enable the instance or ensure paths don't overlap before scanning.

Docker: Local Filesystem Access

Several qui features require access to the same filesystem paths that qBittorrent uses (orphan scan, hardlinks, reflinks, automations).

Mount the same paths qBittorrent uses - paths must match exactly:

volumes:
  - /config:/config
  - /data/torrents:/data/torrents  # Must match qBittorrent's path

After mounting, enable Local Filesystem Access on each instance in qui's Instance Settings.

Important: Abandoned Directories​

Directories are only scanned if at least one torrent points to them. If you delete all torrents from a directory, that directory is no longer a scan root and any leftover files there won't be detected.

Example: You have torrents in /downloads/old-stuff/. You delete all those torrents. Orphan scan no longer knows about /downloads/old-stuff/ and won't clean it up.

Settings​

SettingDescriptionDefault
Grace periodSkip files modified within this window10 minutes
Ignore pathsDirectories to exclude from scanning-
Scan intervalHow often scheduled scans run24 hours
Max files per runMaximum orphan preview entries saved for a run (also caps what can be deleted from that run)1,000
Auto-cleanupAutomatically delete orphans from scheduled scansDisabled
Auto-cleanup max filesOnly auto-delete if orphan count is at or below this threshold100
Default ignores

Orphan Scan skips common OS/NAS metadata, recycle bin, snapshot, and Kubernetes volume-internal entries automatically (case-insensitive).

Ignored files (exact names)

  • .DS_Store
  • .directory
  • desktop.ini
  • Thumbs.db

Ignored files (name prefixes)

  • .fuse* (e.g. .fuse_hidden*)
  • .nfs*
  • ._*
  • .goutputstream-*
  • .#*
  • ~$*

Ignored files (name suffixes)

  • *.parts (qBittorrent partial download files)

Ignored directories (exact names)

  • .AppleDB
  • .AppleDouble
  • .TemporaryItems
  • .Trashes
  • .Recycle.Bin
  • .recycle
  • .snapshot
  • .snapshots
  • .zfs
  • @eaDir
  • $RECYCLE.BIN
  • #recycle
  • lost+found
  • System Volume Information

Ignored directories (name prefixes)

  • .Trash-*
  • ..* (Kubernetes internals like ..data and timestamp dirs)

Max Files Per Run Behavior​

  • Scan scope is still full: qui walks all scan roots each run.
  • Then it sorts orphan candidates by your selected preview sort.
  • Then it applies Max files per run and marks the run as truncated when more candidates exist.
  • Deletion only operates on files saved in that run's preview list.

Example: If 5,000 files are scanned, 2,000 are orphan candidates, and Max files per run is 1,000, qui scans all 5,000, saves the top 1,000 candidates for preview/deletion, and marks the run truncated.

FAQ​

Do I need multiple runs to scan everything? No. Each run scans all roots. Multiple runs are only needed if you want to work through orphan candidates beyond the per-run preview cap.

Workflow​

  1. Trigger a scan (manual or scheduled)
  2. Review the preview list of orphan files
  3. Confirm deletion
  4. Files are deleted and empty directories cleaned up

Preview Features​

  • Path column - Shows the full file path with copy-to-clipboard support
  • Export CSV - Download the full preview list (all pages) as a CSV file