Skip to main content
Documentation Status https://github.com/MacHu-GWU/imgsqueeze-project/actions/workflows/main.yml/badge.svg https://codecov.io/gh/MacHu-GWU/imgsqueeze-project/branch/main/graph/badge.svg https://img.shields.io/pypi/v/imgsqueeze.svg https://img.shields.io/pypi/l/imgsqueeze.svg https://img.shields.io/pypi/pyversions/imgsqueeze.svg https://img.shields.io/badge/✍️_Release_History!--None.svg?style=social&logo=github https://img.shields.io/badge/⭐_Star_me_on_GitHub!--None.svg?style=social&logo=github
https://img.shields.io/badge/Link-API-blue.svg https://img.shields.io/badge/Link-Install-blue.svg https://img.shields.io/badge/Link-GitHub-blue.svg https://img.shields.io/badge/Link-Submit_Issue-blue.svg https://img.shields.io/badge/Link-Request_Feature-blue.svg https://img.shields.io/badge/Link-Download-blue.svg

Welcome to imgsqueeze Documentation

https://imgsqueeze.readthedocs.io/en/latest/_static/imgsqueeze-logo.png

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)

Source distribution for imgsqueeze 0.1.1
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)

Table of built distributions (wheels) for imgsqueeze 0.1.1
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page