https://github.com/georgekhananaev/py-image-compressor

Efficient and expeditious software designed for the swift compression, conversion, and resizing of multiple images simultaneously.
https://github.com/georgekhananaev/py-image-compressor

bulk-image-optimizer heic image-compression image-processing image-resizer jpeg media-converter png python python3 webp

Last synced: 3 months ago
JSON representation

Efficient and expeditious software designed for the swift compression, conversion, and resizing of multiple images simultaneously.

• Host: GitHub
• URL: https://github.com/georgekhananaev/py-image-compressor
• Owner: georgekhananaev
• License: mit
• Created: 2022-11-30T13:43:54.000Z (over 2 years ago)
• Default Branch: main
• Last Pushed: 2025-04-13T09:23:27.000Z (3 months ago)
• Last Synced: 2025-04-13T09:46:35.771Z (3 months ago)
• Topics: bulk-image-optimizer, heic, image-compression, image-processing, image-resizer, jpeg, media-converter, png, python, python3, webp
• Language: Python
• Homepage:
• Size: 8.29 MB
• Stars: 33
• Watchers: 5
• Forks: 5
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
# Python Bulk Image Compressor

[![PyPI](https://img.shields.io/pypi/v/py-bulk-image-compressor.svg)](https://pypi.org/project/py-bulk-image-compressor/)

[![Python Versions](https://img.shields.io/pypi/pyversions/py-bulk-image-compressor.svg)](https://pypi.org/project/py-bulk-image-compressor/)

**py-bulk-image-compressor** is a user-friendly CLI tool for compressing and resizing images in bulk. It offers extensive options for managing image quality, format, and metadata while maintaining fast, efficient performance.

![terminal](https://raw.githubusercontent.com/georgekhananaev/py-image-compressor/main/screenshots/multicore.gif)

### Key Features

- **Supports Multiple Formats:** JPEG, PNG, WEBP, AVIF, HEIF, and more.

- **Metadata Handling:** Choose whether to preserve or remove EXIF data.

- **Multicore Processing:** Utilizes all available CPU cores.

- **Flexible Settings:** Customize output quality, max width, and destination directory.

## Installation

### From PyPI

```bash

pip install py-bulk-image-compressor

```

> **Requires Python 3.10+**

### From Source

1. Clone the repository:

   ```bash

   git clone https://github.com/georgekhananaev/py-image-compressor.git

   cd py-image-compressor

   ```

2. Install dependencies:

   ```bash

   pip install -r requirements.txt

   ```

3. Install locally:

   ```bash

   pip install .

   ```

4. Run the CLI:

   ```bash

   py-bulk-image-compressor -h

   ```

## Usage

After installation, you can run:

```bash

py-bulk-image-compressor -h

```

### Example Commands

1. **Basic compression and resize**:

   ```bash

   py-bulk-image-compressor -l "path/to/original_images" -d "path/to/output"

   ```

   Uses default format (`jpeg`), quality=80, max_width=1920px.

2. **Specific format and quality**:

   ```bash

   py-bulk-image-compressor -l "path/to/original_images" \

       -d "path/to/output" -f webp -w 800 -q 70

   ```

   

3. **Remove metadata & skip larger compressed files**:

   ```bash

   py-bulk-image-compressor -l "path/to/original_images" \

       -d "path/to/output" -rm y -r y

   ```

Logs are saved to logs.txt in the current cmd/terminal working directory. Installation & Usage screenshot below:

![terminal](https://raw.githubusercontent.com/georgekhananaev/py-image-compressor/main/screenshots/usage_example_pypi.png)

### Command-Line Options

| Option | Required | Default Value       | Description                                                            |

|-------:|:--------:|:-------------------:|:-----------------------------------------------------------------------|

| `-l`   | **Yes**  | *(No Default)*      | Input directory for original images. *(Example: `-l "C:/images/"`)*    |

| `-d`   | No       | `/data/output/`     | Output directory for compressed images.                                |

| `-f`   | No       | `jpeg`              | Output format (e.g., `webp`, `png`, `avif`).                           |

| `-w`   | No       | `1920`              | Maximum width (px).                                                    |

| `-q`   | No       | `80`                | Image quality (0-100).                                                 |

| `-r`   | No       | `n` (off)           | Remove compressed if it’s larger than the original (`-r y`).           |

| `-rm`  | No       | `n` (off)           | Remove all metadata (`-rm y`).                                         |

---

## Logging

- Generates or appends to a `logs.txt` file in your current working directory.

- The `configurations.ini` file controls log settings (e.g., `max_rows`).

---

## Contributing

1. Fork the repository.

2. Create a new branch: `git checkout -b feature-name`.

3. Commit your changes: `git commit -m "Add awesome feature"`.

4. Push to your branch: `git push origin feature-name`.

5. Open a pull request on GitHub.

---

## License

This project is licensed under the [MIT License](LICENSE).

---

## Questions or Issues?

- [Open an issue](https://github.com/georgekhananaev/py-image-compressor/issues) on GitHub

- Contributions, suggestions, and bug reports are welcome!

---

## Support

If you find this tool helpful, consider supporting:

[![Buy Me A Coffee](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/georgekhananaev)

Your support helps me continue to create and maintain useful projects.

---

## Updates

#### **13/04/2025**

1. Added JPEG normalization step to ensure consistent color‑space conversion and correct chroma placement.  

2. Upgraded compressor to use progressive encoding, optimized Huffman tables, and 4:2:0 subsampling by default for smaller output sizes.  

3. Added official support for Python 3.13.x.

#### **27/01/2025**

1. Deployed to pypi, **installation**:

    ```shell

      pip install py-bulk-image-compressor

    ```

   **usage**:

    ```shell

      py-bulk-image-compressor -h

    ```

#### **26/01/2025**

1. EXIF metadata is preserved if supported by the output format (e.g., JPEG).

2. Added support for `.avif` format (requires `pillow-avif-plugin`).

3. Minor speed optimizations for faster compression.

4. Updated `requirements.txt` with the latest package versions.

5. Added logs, which is exported to logs.txt

6. Added tests, use 

    ```shell

      pytest --maxfail=1 --disable-warnings -v

    ```

#### **02/12/2023**

1. Automatic detection and handling of RGB/RGBA channels.

2. Thanks to "ZenithVal" for the suggestion.

#### **06/04/2023**

1. Updated `README.md`.

2. Updated `requirements.txt` with the latest package versions.

#### **12/12/2022**

1. Introduced a `resources` folder containing `configurations.ini` for storing program settings.

2. Set up future GUI plans using `customtkinter`.

3. Removed PySimpleGUI from dependencies.

#### **06/12/2022**

1. Default values added for `-d`, `-f`, and `-q` options. You can run:

   ```

   python main.py -l "C:/Your Folder/"

   ```

   Defaults: JPEG format, 80% quality, 1920px max width, `/data/output/` as the destination folder.

2. Simplified the code using `*args` and `**kwargs`.

#### **05/12/2022**

1. Added support for `.heif` and `.heic` formats (e.g., iPhone photos).

2. Updated `requirements.txt` to include `pillow-heif`.

#### **04/12/2022**

1. Improved the output to display the actual size saved for each image, with full multithreading conversion support.

2. Enhanced terminal output for better visualization of size savings.

3. Began GUI development for Windows and Ubuntu.

4. Added `-r y` to skip retaining larger compressed images.