photo-organizer

KO | EN

gitlite — search

#python #typescript #golang #deep-learning #docker #macos #windows #kubernetes #awesome-list #pytorch #security #ios #openai #open-source

photo-organizer

(★ 36)

A simple python script to sort or reorganise your collection of images or RAWs. Or just any files you want to sort by creation date.

photo-organizer Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Photo Organizer
[![Tests](https://github.com/Supporterino/photo-organizer/actions/workflows/python-package.yml/badge.svg)](https://github.com/Supporterino/photo-organizer/actions/workflows/python-package.yml)[![Upload Release](https://github.com/Supporterino/photo-organizer/actions/workflows/python-publish.yml/badge.svg)](https://github.com/Supporterino/photo-organizer/actions/workflows/python-publish.yml)[![PyPI version](https://badge.fury.io/py/photo-organizer.svg)](https://badge.fury.io/py/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:

```bash
pip install photo-organizer
```

Alternatively, use it with Docker:

```bash
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

```bash
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:

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

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

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

Copy only `.jpg` and `.png` files:

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

Exclude files matching a specific regex pattern:

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

Enable verbose logging:

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

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

```bash
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:

```bash
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.

photo-organizer

photo-organizer Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

photo-organizer

photo-organizer Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README