Years of my work were on one portable SSD. One day I plugged it in and macOS refused to mount it. The drive was there, but its APFS volume wouldn't open.
The paywall
I did what everyone does and searched for recovery software. Every option was a subscription or a paid licence. The free versions scanned my drive, showed me my own files, and then stopped: a 100 MB limit here, a 2 GB cap there. Pay first, then you get your files back.
They were my files, on my drive, and the software could clearly read them. That felt wrong.
The script
I'm a developer, so I started reading how APFS actually stores things. The damage was in the volume's bookkeeping, not in the files themselves.
So I wrote a small rescue tool that:
- opened the drive strictly read-only,
- found the newest part of the file system that still held together (the newest usable checkpoint),
- walked the folder tree from there, and
- copied everything off.
It worked. My files came back.
The rules I kept
A recovery tool touches someone's only copy of something, so I kept a few rules from the first script:
- Never write to the source drive. It's opened with read-only system handles. Nothing formats, partitions or touches blocks on the damaged disk.
-
Never delete for real. Anything cleaned up goes to the Trash or Recycle Bin, not
rm. -
Never overwrite a copy. Files are written as
.partand renamed only after they're verified. Name clashes becomefilename.retrova-N. -
Stay local. The engine binds only to
127.0.0.1with a session token, sends no analytics, and only talks to the internet when you click Check for updates.
Then the questions started
Getting files back was half of it. Is every copy really intact? Why is my backup drive suddenly full? Which folders are copies of each other? Each answer became a tool:
- Verify: compare recovered copies against the original drive in Quick (name and size), Sample (head/tail hash) or Full (byte-for-byte) mode, then recopy anything that doesn't match.
- Rescue more file systems: APFS, HFS+, NTFS, FAT and exFAT, ext2/3/4, XFS and Btrfs, plus BitLocker, LUKS and FileVault volumes when you have the key.
- Deleted files with their names on NTFS, FAT and exFAT, and file carving for 72 formats (camera RAW, HEIC, PST and more) when there's no file system left.
-
Careful imaging of failing drives, the way GNU ddrescue does it: save the healthy areas first, skip ahead on read errors, then come back for the damaged parts. Progress goes into a ddrescue-compatible
.mapfile, so you can stop and resume. - Reclaim space: sparse-file fixes for VM and Docker disks, APFS clones for duplicates, and a dev-cache cleaner.
Together they became Retrova.
How it's built
It's plain Python with a no-build-step web UI. You can run it from source:
python3 -m venv .venv && source .venv/bin/activate
pip install -r packaging/requirements/common.txt -r packaging/requirements/mac.txt # or win.txt
python -m retrova
Add &mock=1 to the URL to try the interface without touching any drive. Release builds come from GitHub Actions and carry a signed build attestation, so you can check a download with:
gh attestation verify Retrova-1.1.3-mac-arm64.dmg --repo jishnumahanta/retrova
The builds aren't signed with a paid Apple or Microsoft certificate yet, so macOS Gatekeeper and Windows SmartScreen show a warning on first launch. The README explains how to get past it, and how to check the SHA-256.
Why it's free, and open
Retrova is free for anyone rescuing their own files. No trial, no account, no recovery limit. It's open source under the AGPL-3.0, because a tool you trust with your only copy of something should be one you can read: it reads, and it never writes.
- Download (macOS + Windows): https://retrova.jishnumahanta.in
- Source: https://github.com/jishnumahanta/retrova
If you've ever stared at a drive that won't open, I'd like to know what you tried first. And if Retrova saves your files, tell one friend.
— Jishnu Mahanta, independent developer in Guwahati, India
Top comments (0)