English · Español
A command-line tool that takes a messy folder of photos and videos and files it
into a clean YYYY/MM library. Built for large local and external-drive photo
collections where duplicates, RAW+JPG pairs, DJI sequences, and inconsistent
metadata are common.
- Metadata-first dating — EXIF for images,
exiftool/mdlsfor videos, with filesystem dates as a fallback. - Duplicate detection — file size plus a partial hash, then a full hash only when needed.
- Destination index — catches files that already exist in the destination even if they were renamed or reorganized.
- DJI sequence grouping — keeps panoramas, hyperlapses, timelapses, and bursts in the same folder.
- RAW+JPG pairing — keeps sidecar files together.
- Post-transfer verification — compares hashes after copying.
- Collision handling — appends
_1,_2, and so on instead of overwriting. - Dry-run first — scans and reports without changing anything.
- JSON transaction log —
TRANSFER_LOG_<timestamp>.jsonin the destination. - Copy or move — copy is the default; move removes files from the source.
- Python 3.10+
- Pillow
- ExifTool (recommended for reliable video metadata)
- macOS for the
mdlsfallback andcaffeinatesleep prevention
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
brew install exiftool # optional, but recommendedAlways run a dry run first:
python3 photov5.py /Volumes/Photos /Volumes/PhotoBackup --dry-runThen run the copy:
python3 photov5.py /Volumes/Photos /Volumes/PhotoBackup --mode copyOr set the paths once with environment variables:
export PHOTO_SOURCE="/Volumes/Photos"
export PHOTO_DEST="/Volumes/PhotoBackup"
python3 photov5.py --dry-run| Option | Description |
|---|---|
--mode {copy,move} |
Copy files (default) or move them out of the source. |
--org-mode {metadata_first,oldest,created,modified} |
How the file date is chosen. |
--sequence-window MINUTES |
Time window for grouping DJI sequence files. |
--skip-folder NAME |
Skip a folder name; repeat for multiple folders. |
--no-verify |
Skip the post-transfer hash check. |
--no-log |
Do not write the JSON transaction log. |
--no-dest-index |
Skip indexing the destination before scanning. |
--dry-run |
Scan and report only; never transfer files. |
--yes |
Skip confirmation prompts. Use only after reviewing the dry run. |
--yes also skips the move confirmation, so review the dry run before using it
with --mode move.
Files are placed under the destination using their resolved date:
PhotoBackup/
├── 2023/
│ ├── 05/
│ └── 11/
├── 2024/
│ └── 02/
└── TRANSFER_LOG_20260530_142501.json
WhatsApp filenames contain the original timestamp, but the file metadata often
does not. whatsappRename.py copies that timestamp into EXIF/video tags:
python3 whatsappRename.py ~/Desktop/fotos --dry-run
python3 whatsappRename.py ~/Desktop/fotosIt scans recursively and only touches recognized WhatsApp media names.
- Scans the source and classifies images, videos, sidecars, and DJI sequences.
- Resolves the best available date for each file.
- Groups DJI sequences and RAW+JPG pairs.
- Builds a destination index and skips duplicates.
- Copies or moves files into
YYYY/MM. - Verifies hashes and writes a transaction log.
- Copy is the default. Keep it that way until you have verified the result.
- Use a powered connection for external drives and keep the Mac awake.
- Do not disconnect drives while a transfer is running.
- The script never overwrites an existing destination file; it picks a new name.
- Files land in the wrong month: install
exiftool; without it the script may fall back to filesystem dates. - Permission denied on an external drive: grant Terminal Full Disk Access and reconnect the drive.
- You need to undo a move: restore from your backup. Use
--mode copyuntil the dry run looks correct.
MIT — see LICENSE.