Photo Renamer

lupaxa-photo-renamer safely copies or moves photographs and videos into consistent, date-based filenames. The console command is photo-renamer.

It reads image EXIF or video metadata when available, falls back to filesystem modification time in the default mode, detects common source apps from filenames, and reports progress with Rich.

Installation

Python 3.13 or newer is required.

pip install lupaxa-photo-renamer

Using a virtual environment is recommended:

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install lupaxa-photo-renamer

For local development:

git clone https://github.com/lupaxa-miscellaneous-toolbox/photo-renamer.git
cd photo-renamer
python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

Video timestamp extraction uses MediaInfo. If it is missing, install it with your operating system's package manager (brew install mediainfo on macOS, apt install mediainfo on Debian/Ubuntu). auto still falls back to filesystem modification time.

Quick Start

PATH is the directory to scan. Preview the work first:

photo-renamer --dry-run --recursive ~/Pictures

Review the startup panel (root, output, operation, format, timestamp mode, file count). Then run the same command without --dry-run:

photo-renamer --recursive ~/Pictures

By default, files are copied, originals remain untouched, and results are written below PATH/renamed/. Only files directly inside PATH are scanned unless you add --recursive. Existing relative directories are preserved:

Pictures/holiday/day-1/IMG-20260801-WA0001.JPG
→ Pictures/renamed/holiday/day-1/2026-08-01_14-55-22.jpg

Use --move only when you intentionally want to remove each successfully processed source.

Common Examples

# Include a detected source label in each filename
photo-renamer --recursive --format source ~/Pictures

# --preserve-source is an alias for --format source
photo-renamer --preserve-source ~/Pictures

# Put a source folder inside each preserved relative path
photo-renamer --recursive --organise ~/Pictures
# → renamed/holiday/day-1/WhatsApp/2026-08-01_14-55-22.jpg

# Drop relative paths, retaining only source folders
photo-renamer --recursive --flatten --organise ~/Pictures
# → renamed/WhatsApp/2026-08-01_14-55-22.jpg

# Choose another output root and move instead of copy
photo-renamer --recursive --output /Volumes/Archive --move ~/Pictures

# Limit extensions and always use modification time
photo-renamer --recursive --include jpg,jpeg,heic --timestamp filesystem ~/Pictures

A relative --output resolves below PATH. --verbose and --quiet cannot be used together.

Flag Summary

If both --format and --preserve-source are supplied, the explicit --format value wins.

--workers only parallelises copy or move. Planning stays sequential so collision-safe names stay stable. If --workers is greater than twice the detected CPU count, photo-renamer asks for confirmation (use --yes in CI).

--log-file is not written during --dry-run. Each line is timestamp, action, source, destination, source label, timestamp origin, and message.

Run photo-renamer --help for the authoritative command syntax.

Filename Formats

Extensions are preserved and lowercased. datetime is the default.

For PATH/vacation/day-1/IMG-20260801-WA0001.jpg:

--organise nests the detected source inside the preserved relative path.

Supported Formats

Matching is case-insensitive. --include and --exclude filter this supported set; they do not enable arbitrary formats.

Timestamps

Every output name uses a resolved timestamp as YYYY-MM-DD_HH-MM-SS.

Image priority: EXIF DateTimeOriginal, then DateTimeDigitized, then DateTime, then filesystem mtime when the mode allows fallback.

Video priority: MediaInfo recorded, creation, encoded, then tagged dates, then filesystem mtime.

--timezone ZONE accepts IANA identifiers such as Europe/London. The tool reads metadata only; it never rewrites EXIF or video tags.

Source Detection

Rules are case-insensitive; the first match wins. Detection uses the original filename only — not pixels or maker tags.

Safety

Unreadable subdirectories are skipped without aborting the run. A mistyped PATH is a configuration error.

Exit Codes

Troubleshooting

Files inside the resolved output directory are ignored. Symlinks are not followed. --timestamp exif fails any file that has no embedded date.

FAQ

Testing

make init
make python-install-dev
make python-check

Or without Make:

python -m pip install -e ".[test]"
pytest

Coverage for lupaxa.photo_renamer is reported by default.

This project is released under the MIT License; see LICENCE.