iPod Health Checks

podkit doctor is a diagnostic tool that checks your iPod for common problems and can repair them automatically. You don’t need to use podkit as your sync tool to benefit from it — it works on any iPod with a standard database.

Quick Start

Connect and mount your iPod, then run:

podkit doctor

podkit scans the iPod and reports what it finds:

podkit doctor — checking iPod at /Volumes/TERAPOD

  ✓ Artwork Integrity    2,532 entries, 2 formats (1028, 1029), all offsets valid
  ✓ Orphan Files         No orphaned files found

All checks passed.

If problems are detected, doctor tells you what’s wrong and how to fix it. You don’t need a podkit config file or music collection to run diagnostics — some repairs work standalone too.

Available Health Checks

Check	What it detects	Severity
Artwork Integrity	Corrupted artwork database — wrong album art, glitched images, artwork from other albums	Failure
Orphan Files	Unreferenced audio/video files wasting storage space	Warning

Repairing Artwork Corruption

If doctor reports artwork corruption, you have two repair options.

Reset artwork (no source collection needed)

The fastest fix. Clears all artwork from the iPod and removes artwork sync tags. Your music stays untouched — only the artwork is removed.

podkit doctor --repair artwork-reset

This is useful when:

You don’t have your source collection available
You don’t use podkit for syncing and just want to clear corrupted artwork
You want a quick fix and plan to re-sync artwork later

If you sync with podkit, the next podkit sync will re-add artwork from your source files automatically. If you sync with iTunes or another tool, re-sync from that tool to restore artwork.

Rebuild artwork from source

Rebuilds all artwork in one step by matching each track back to your source files and re-extracting the cover art:

podkit doctor --repair artwork-rebuild -c main

This requires a configured music collection (-c). What the rebuild does:

Removes all existing artwork from every track on the iPod
Matches each track back to its source file using artist, title, and album metadata
Re-extracts artwork from the source files and applies it to the iPod
Saves the database — writes completely fresh thumbnail files

Audio files, playlists, play counts, ratings, and track metadata are not modified.

Choosing between them

	Reset (`artwork-reset`)	Rebuild (`artwork-rebuild`)
Speed	Fast (seconds)	Slower (reads source files)
Source collection needed	No	Yes
Result	Artwork cleared, re-added on next sync	Artwork rebuilt immediately
Best for	Quick fix, non-podkit users	One-step permanent repair

After repair

Run podkit doctor again to verify the repair was successful. Eject the iPod safely before disconnecting to ensure all data is flushed to disk:

podkit doctor
podkit eject

Repairing Orphan Files

Orphan files are audio or video files on the iPod that aren’t referenced by the database. They waste storage but don’t cause other problems. This typically happens after an interrupted sync (force-quit, crash, or disconnection during transfer).

# Preview what would be deleted
podkit doctor --repair orphan-files --dry-run

# Remove orphaned files
podkit doctor --repair orphan-files

Previewing Repairs

Every repair supports --dry-run to preview changes without modifying anything:

podkit doctor --repair artwork-reset --dry-run
podkit doctor --repair artwork-rebuild -c main --dry-run
podkit doctor --repair orphan-files --dry-run

Additional Options

Use --verbose for detailed diagnostic output (e.g., orphan file breakdowns by directory and extension). Export orphan file lists as CSV with --format csv. Pressing Ctrl+C during a repair triggers a graceful shutdown — partial progress is saved before exiting.