photo-organizer 2.0.0

A script to organize photos by creation date into year/month/day folders.

Photo Organizer

Photo Organizer is a Python script that sorts photos from a source directory into a target directory based on their creation date. The script can organize photos into year, month, and optionally day subfolders. It also supports explicitly choosing whether to copy or move files, recursive directory traversal, filtering by file extensions, and excluding files using regex patterns.

Features

• Organize photos into year/month/day folders based on creation date
• Explicitly copy or move files from the source to the target directory (--copy or --move, one required)
• Recursively traverse directories
• Filter files by specified extensions
• Exclude files from processing using regex patterns
• Verbose logging for detailed information
• Flexible folder structure with optional top‑level year‑month folders

Usage

Prerequisites

• Python 3.x

Installation

Install the package using pip:

pip install photo-organizer

Alternatively, use it with Docker:

docker run -ti \
    -v <your-photo-source-directory>:/source \
    -v <your-photo-target-directory>:/target \
    ghcr.io/Supporterino/photo-organizer:latest /source /target

Running the Script

photo-organizer [-h] [-r] [-d] [-e [ENDINGS ...]] [-v]
                 [-c | -m] [--no-year] [--exclude EXCLUDE_PATTERN]
                 source target

Arguments

• SOURCE_DIRECTORY – The source directory containing the photos
• TARGET_DIRECTORY – The target directory where the photos will be organized

Options

Flag	Description
-r, --recursive	Sort photos recursively from the source directory
-d, --daily	Organize photos into daily folders (year/month/day)
-e, --endings	Specify file endings/extensions to process (e.g., .jpg .png). If omitted, all files are included
--exclude	Provide a regex pattern to exclude matching files from being processed
-v, --verbose	Enable verbose logging (-vv for more detail)
-c, --copy	Copy files instead of moving them
-m, --move	Move files instead of copying (default when this flag is used)
--no-year	Do not place month folders inside a year folder; use top‑level YEAR-MONTH format
--no-progress	Disable progress bar for fully automated environments
--delete-duplicates	Delete source file if an identical file already exists in the target directory
--dry-run	Only logs the expected actions and errors but does not modify anything
--exif	Try to parse the creation date from picture EXIF data; falls back to file system timestamp

NOTE: One of -c/--copy or -m/--move must be supplied. If neither is provided, the script will warn and exit.

Examples

Move all files from source to target, organizing by year and month:

photo-organizer --move /path/to/source /path/to/target

Move all files recursively and organize by year/month/day:

photo-organizer --move -r -d /path/to/source /path/to/target

Copy only .jpg and .png files:

photo-organizer -c -e .jpg .png /path/to/source /path/to/target

Exclude files matching a specific regex pattern:

photo-organizer --exclude "^ignore|\.tmp$" /path/to/source /path/to/target

Enable verbose logging:

photo-organizer -vv --move /path/to/source /path/to/target

Move photos to top‑level year‑month folders without a year parent folder:

photo-organizer --no-year --move /path/to/source /path/to/target

Combine options to copy .jpg and .png files recursively into daily folders with verbose logging:

photo-organizer -c -r -d -e .jpg .png -vv /path/to/source /path/to/target

Development

To contribute to this project, follow these steps:

1. Clone the repository.
2. Install dependencies.
3. Make your changes and add tests.
4. Submit a pull request.

Logging

The script uses Python's logging module to provide detailed information about the operations performed. By default, the logging level is set to WARNING. Use the -v or --verbose flag to enable INFO level logging and -vv for DEBUG level logging for more detailed output.

Contributing

Contributions are welcome! Please fork the repository and submit a pull request with your changes. Ensure that your code adheres to the existing coding standards and includes appropriate tests.

License

This project is licensed under the MIT License. See the LICENSE file for details.