Photo Renamer

lupaxa-photo-renamer safely copies or moves photographs and videos into consistent, date-based filenames. It reads image EXIF or video metadata when available, falls back to filesystem modification time in the default mode, detects common source apps, and reports progress with Rich.

A Rich terminal screenshot will be added under mkdocs/assets/. Until then, the startup panel, progress bar, and summary table are shown directly in your terminal.

Installation

Python 3.13 or newer is required.

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 unavailable on your system, install the MediaInfo package with your operating system's package manager.

Quick start

Preview the work first:

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

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/. 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

Flag summary

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

Filename formats

Extensions are preserved and lowercased. datetime is the default.

Supported formats

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

Safety

Troubleshooting

See the usage guide for more detail.

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.

Documentation

The published guide is at https://photo-renamer.thelupaxaproject.org/.

Site Markdown lives in mkdocs/.

python -m pip install -r requirements.txt
make mkdocs-serve

make mkdocs-build builds the site. A strict build is python -m mkdocs build --strict.

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