Optimize Images

A command-line interface (CLI) utility written in pure Python to help you reduce the file size of images.

This application is intended to be pure Python, with no special dependencies besides Pillow and watchdog, therefore ensuring compatibility with a wide range of systems. If you don't have the need for such a strict dependency management, you will probably be better served by any several other image optimization utilities that are based on some well known external binaries.

Some aditional features can be added which require the presence of other third-party packages that are not written in pure Python, but those packages and the features depending on them should be treated as optional.

If you were just looking for the graphical user interface (GUI) version of this application, it's a separate project: Optimize Images X.

Full Documentation:

• English
• Português

Please refer to the above links if you want to know about all the options available in this application. For a quick intro, just to get a feeling of what it can do, please keep reading below.

Installation and dependencies:

To install and run this application, you need to have a working Python 3.11 or later installation. We try to keep the external dependencies at a minimum, in order to keep compatibility with different platforms. At this moment, we require:

• Pillow>=13.0.0
• watchdog>=6.0.0

The easiest way to install it in a single step, including any dependencies, is by using this command:

pip3 install pillow optimize-images

The SSIM quality control options (--ssim-min, --show-ssim) additionally require the optional scikit-image package (pip install scikit-image, or pip install optimize-images[ssim] for the [ssim] extra); without it, --show-ssim prints a warning once and shows no scores, and --ssim-min stops the run with an error.

Any Python from 3.11 to 3.15 works. For large batches, a free-threaded build (Python 3.14t or 3.15t) is several times faster on multi-core machines (about 5x on a batch of photos on a MacBook Pro M5 Pro); see Choosing a Python build.

How to use

The most simple form of usage is to type a simple command in the shell, passing the path to an image or a folder containing images as an argument. The optional -nr or --no-recursion switch argument tells the application not to scan recursively through the subdirectories.

By default, this utility applies lossy compression to JPEG files using a variable quality setting between 75 and 80 (by Pillow's scale), that is dynamically determined for each image according to the amount of change caused in its pixels, then it removes any EXIF metadata, tries to optimize each encoder's settings for maximum space reduction and applies the maximum ZLIB compression on PNG. WebP images are re-encoded to reduce their size while preserving any transparency.

You must explicitly pass it a path to the source image file or to the directory containing the image files to be processed. By default, it will scan recursively through all subfolders and process any images found using the default or user-provided settings, replacing each original file by its processed version if its file size is smaller than the original.

If no space savings were achieved for a given file, the original version will be kept instead.

There are many other features and command-line options, like downsizing, keeping EXIF data, color palette reduction, WebP optimization, PNG to JPEG (or WebP) conversion, and smaller JPEG files by default thanks to mozjpeg's quantization table (see -jt). Please check the docs for further information.

DISCLAIMER:
Please note that the operation is done DESTRUCTIVELY, by replacing the original files with the processed ones. You definitely should duplicate the source file or folder before using this utility, in order to be able to recover any eventual damaged files or any resulting images that don't have the desired quality.

Basic usage

Try to optimize a single image file:

optimize-images filename.jpg

Try to optimize all image files in current working directory and all of its subdirectories:

optimize-images ./

Try to optimize all image files in current working directory, without recursion:

optimize-images -nr ./

optimize-images --no-recursion ./

For developers

Besides the command-line interface, Optimize Images exposes a small, stable, UI-free API for use in your own Python applications, in the optimize_images.api module (since version 2.0.0). It can optimize a single image or a whole folder, with no terminal output.

from optimize_images.api import optimize_single_image

result = optimize_single_image("photo.jpg", quality=70, max_w=1920)
print(result.orig_size, "->", result.final_size)

For batch processing, directory watching, the full set of options and the result fields, see Programmatic use in the full documentation.

To run the tests (python -m pytest, or python scripts/test_matrix.py for every supported Python version), see Running the tests.

Getting help

To check the list of available options and their usage, you just need to use one of the following commands:

optimize-images -h

optimize-images --help

Did you find a bug or do you have a suggestion?

Please let me know, by opening a new issue or a pull request.