Fotura

A Python CLI for importing, organizing, and uploading your photos.

Fotura moves photos from a source directory into a clean, date-organised folder structure. It extracts timestamps from EXIF metadata and filenames, resolves conflicts, and can upload directly to Google Photos, all from a single command.

Installation

pipx install fotura

Usage

fotura import ~/Pictures/unsorted ~/Pictures/organized

Always preview first with --dry-run:

fotura import ~/Pictures/unsorted ~/Pictures/organized --dry-run --open-report

To process multiple photos at once, use --concurrency (default: 1, maximum: 5).

fotura import ~/Pictures/unsorted ~/Pictures/organized --concurrency 2

Reports are generated for each import, viewable using your browser:

Processors

Processors extend the import pipeline. Specify them with --before-each, --after-each, or --after-all. Multiple processors can be chained by repeating the flag.

Before-each processors run prior to a photo being moved. They extract facts, such as a timestamp from a filename, which inform how the photo is routed and processed.

Filename Timestamp Extract

Extracts timestamps from WhatsApp and Android filenames and writes them back into EXIF metadata.

fotura import --before-each "filename_timestamp_extract" ~/Pictures/unsorted ~/Pictures/organized

Video Timestamp Extract

Extracts the creation timestamp stored in MP4, M4V, MOV, 3GP, and 3G2 video containers. The timestamp is used to route the video without modifying the file.

Choose media types with the repeatable --include option. Photos are selected by default; select videos alone or explicitly select both:

# Videos only
fotura import ~/Videos/unsorted ~/Videos/organized --include videos --before-each "video_timestamp_extract"

# Photos and videos
fotura import ~/Pictures/unsorted ~/Pictures/organized --include photos --include videos

Google Photos Upload

Uploads in parallel after the full import completes, using the Google Photos batch API for efficiency.

fotura import --after-all "google_photos_upload" ~/Pictures/unsorted ~/Pictures/organized
fotura import --after-all "google_photos_upload:concurrency=3,batch_size=20" ~/Pictures/unsorted ~/Pictures/organized

The Google Photos processor is resumable. Interrupted or failed uploads can be retried without re-uploading photos that already succeeded:

fotura processor resume google_photos_upload

Supported file types

Photos

Videos

Options

Path format

Photos are organised into %Y/%Y-%m by default (e.g. 2023/2023-05). Override with --target-path-format using Python date format codes:

Conflict resolution

The default conflict strategy is keep_both.

• keep_both: appends a numeric suffix to the incoming file (photo_1.jpg, photo_2.jpg, …)
• skip: leaves the existing file in place and skips the incoming one

Coming soon

• Stripping location data from EXIF.
• Flagging low-quality images (blurry, over/under-exposed, duplicates).
• Image labelling via a multimodal LLM.

Development

See Development.