Welcome to imgsqueeze Documentation
imgsqueeze compresses the PNG, JPEG and WebP images of a blog once, and remembers that they are done.
Visually lossless presets. PNG goes through pngquant and oxipng; JPEG and WebP are re-encoded with Pillow. A result is kept only when it saves enough bytes; otherwise the original stays untouched.
Done is done. Each image gets a small <image>.json sidecar that records the hash of its final content. Running again skips it, whatever the preset, so no image is ever compressed twice.
Safe to run anywhere, any time. Files are replaced atomically, and an image changed by another process while it was compressed is left alone.
Made for agents. --json output, stable exit codes, and a check command for pre-commit hooks.
$ imgsqueeze optimize ~/blog/images
optimized /Users/me/blog/images/cover.jpg 419423 -> 76176 bytes (81.8% saved)
optimized /Users/me/blog/images/diagram.png 55537 -> 7793 bytes (86.0% saved)
no_gain /Users/me/blog/images/hero.webp 373482 -> 373482 bytes (0.0% saved)
3 images: 2 optimized, 1 no_gain; saved 390991 bytes
Commit the images together with their .json sidecars. Read the full documentation at https://imgsqueeze.readthedocs.io/.
Install
imgsqueeze needs Python 3.11+ and mise. mise installs the pinned pngquant and oxipng the first time a PNG is compressed; JPEG and WebP need nothing else. Run it without installing:
$ uvx imgsqueeze optimize ~/blog/images
Or install it from PyPI:
$ pip install imgsqueeze
To install pngquant and oxipng ahead of time:
$ imgsqueeze setup
Use with AI Coding Agents
This repo ships an Agent Skill that documents the public API of imgsqueeze, so an AI coding agent such as Claude Code can use the library without reading its source. It lives in .claude/skills/pypi-imgsqueeze. To use it in your project, copy it into your project’s .claude/skills/ folder. Run this from your project’s root:
$ git clone --depth 1 https://github.com/MacHu-GWU/imgsqueeze-project.git /tmp/imgsqueeze-project
$ mkdir -p .claude/skills
$ cp -R /tmp/imgsqueeze-project/.claude/skills/pypi-imgsqueeze .claude/skills/
License
imgsqueeze is MIT licensed. It runs pngquant, by Kornel Lesiński and contributors, as a separate program and never bundles it; pngquant is dual-licensed under GPL-3.0 or a commercial license, and the images it produces are not covered by its license.
Metadata
Release files for imgsqueeze 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| imgsqueeze-0.1.1.tar.gz | 43.3 kB | Without provenance | Details for imgsqueeze-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| imgsqueeze-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for imgsqueeze-0.1.1-py3-none-any.whl |
Total release size: 78.0 kB
Release files / imgsqueeze-0.1.1.tar.gz
| Download URL | imgsqueeze-0.1.1.tar.gz |
|---|---|
| Size | 43.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a246404196367302d08b1cdc1df421a798034524de1f70f25cd28749ae62b751
|
|
BLAKE2b-256 checksum How to use checksums |
6be017fb6d50e5a51637fb2956aa21c479ebf95a978fd440868e22590acf2646
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / imgsqueeze-0.1.1-py3-none-any.whl
| Download URL | imgsqueeze-0.1.1-py3-none-any.whl |
|---|---|
| Size | 34.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c788180c19c35520d1217787521cbf7a44a96f70547399886ee6a047dd234202
|
|
BLAKE2b-256 checksum How to use checksums |
eba1d6ddeb122758c7d60413cd57f1f17ce03b90238512276b8ac8e773d8beb4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.7 {"installer":{"name":"uv","version":"0.11.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for imgsqueeze 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.