pixopt 1.0.6

Fast Python image optimizer. Resize, compress, convert, and generate responsive assets.

pixopt

A powerful, easy-to-use Python library and CLI tool for optimizing images for web and storage.

📖 Documentation • 📦 PyPI • 🏷️ Releases

---

Table of Contents

• Overview
• Features
• Installation
• Quick Start
• CLI Usage
  • Commands
  • Global Options
  • Use-Case Recipes
• Library Usage
  • Basic optimization
  • Batch processing
  • Format conversion
  • Lossless compression
  • Adaptive quality
  • Placeholders
  • Smart format detection
  • Responsive srcset
  • Backup and min-size filter
  • Favicon generation
• API Reference
• Development
• Contributing
• Changelog
• License

---

Overview

pixopt is a fast Python image optimizer designed for modern web workflows. It provides both a rich command-line interface (CLI) and a clean Python API to resize, compress, convert formats, generate responsive assets, extract lazy-loading placeholders, and detect the optimal format automatically.

Whether you are a developer automating image pipelines, a designer preparing assets, or a DevOps engineer optimizing static sites, pixopt handles the heavy lifting so you don't have to.

---

Features

• 🖼️ Format conversion — JPEG, PNG, WEBP, AVIF, GIF, HEIC/HEIF, SVG
• 🎞️ Animated GIF → WEBP — convert animated GIFs to much lighter animated WEBP
• 🧹 SVG minification — pure-Python SVG cleanup (no Node.js tools needed)
• 📱 HEIC/HEIF import — open iPhone photos directly via pillow-heif
• 🎯 Lossless mode — lossless PNG/WEBP compression for UI assets that need pixel-perfect fidelity
• 🔍 Adaptive quality — binary-search quality to hit a target file size automatically
• 📊 Visual comparison — generate interactive HTML before/after sliders
• 📐 Responsive srcset — generate multiple width variants and HTML <img srcset="..."> snippets
• 🎨 Lazy-loading placeholders — extract dominant color, generate LQIP data URIs, or blurhash strings
• 🧠 Smart format detection — auto-detect the most efficient format (photo → WEBP, graphic → PNG, transparent → WEBP)
• 💾 Backup originals — copy originals to a backup directory before processing
• ⚡ Batch processing — optimize single files, directories, or multiple files at once
• 💻 Beautiful CLI — built with Typer for an intuitive command-line experience

---

Installation

From PyPI (recommended)

pip install pixopt

With HEIC/HEIF support

pip install pixopt pillow-heif

From source

git clone https://github.com/MathiasPaulenko/pixopt.git
cd pixopt
pip install -e ".[dev]"

Verify installation

pixopt --help

---

Quick Start

=== "CLI"

```bash
pip install pixopt
pixopt optimize photo.jpg --quality 80 --width 1200
```

=== "Library"

```python
from pixopt import optimize_image
from pixopt.models import OutputFormat

result = optimize_image(
    "photo.jpg",
    "photo_optimized.webp",
    max_width=1200,
    quality=80,
    output_format=OutputFormat.WEBP,
)
print(f"Saved {result.savings_percent:.1f}%")
```

---

CLI Usage

The CLI is built with Typer and provides an intuitive interface for all optimization features.

Commands

optimize

Optimize a single image or all images in a directory.

pixopt optimize photo.jpg photo_optimized.jpg --quality 80 --width 1200
pixopt optimize ./images ./optimized --recursive --quality 85 --format webp

batch

Optimize multiple specific files at once.

pixopt batch photo1.jpg photo2.png photo3.bmp -o ./optimized --width 800

convert

Convert an image to a different format or extension.

pixopt convert photo.png photo.webp -f webp
pixopt convert ./images ./webp_images -r -f webp

favicon

Convert an image to a multi-resolution ICO favicon.

pixopt favicon logo.png favicon.ico
pixopt favicon logo.png --size 16 --size 32 --size 48

info

Inspect image metadata without optimizing.

pixopt info photo.jpg

compare

Generate an interactive HTML before/after slider.

pixopt compare photo.jpg comparison.html --open

srcset

Generate responsive image variants and an HTML srcset snippet.

pixopt srcset hero.jpg --sizes 320,640,1024,1920 --output-dir ./responsive/
pixopt srcset hero.jpg --sizes 320,640,1024,1920 -f webp --html snippet.html

placeholder

Extract a placeholder for lazy loading (color, LQIP, or blurhash).

pixopt placeholder photo.jpg --type color
pixopt placeholder photo.jpg --type lqip
pixopt placeholder photo.jpg --type blurhash -o blurhash.txt

Global Options

Option	Short	Description	Default
--quality	-q	JPEG/WEBP quality (1-100)	85
--width	-w	Maximum width in pixels	—
--height	-h	Maximum height in pixels	—
--format	-f	Output format: auto, jpeg, png, webp, avif, original	auto
--strip	-s	Remove metadata	True
--progressive	—	Progressive JPEG encoding	True
--recursive	-r	Process directories recursively	False
--overwrite	—	Overwrite source files	False
--lossless	—	Lossless PNG/WEBP compression	False
--target-size	—	Target file size in KB (adaptive quality)	—
--smart-format	—	Auto-detect the most efficient output format	False
--backup	—	Backup originals to this directory	—
--min-size	—	Skip files already smaller than this threshold (KB)	—

Use-Case Recipes

Lossless PNG/WEBP for UI assets

pixopt convert icon.png icon.webp --lossless -f webp

Adaptive quality (target file size)

pixopt optimize photo.jpg --target-size 50

Smart format detection

pixopt optimize photo.jpg --smart-format
pixopt convert graphic.png output --smart-format

Backup originals before processing

pixopt optimize ./images --backup ./originals --recursive

Skip already-optimized files

pixopt optimize ./images --min-size 10 --recursive

Animated GIF to animated WEBP

pixopt convert animation.gif animation.webp -f webp

Convert HEIC (iPhone) to JPEG

pixopt convert photo.heic photo.jpg

Optimize SVG

pixopt convert icon.svg icon.min.svg

---

Library Usage

pixopt can be used as a Python library for custom workflows and integrations.

Basic optimization

from pixopt import optimize_image
from pixopt.models import OutputFormat

result = optimize_image(
    "photo.jpg",
    "photo_optimized.webp",
    max_width=1200,
    quality=80,
    strip_metadata=True,
    output_format=OutputFormat.WEBP,
)

print(f"Saved {result.savings_percent:.1f}% ({result.human_savings})")
print(f"Output: {result.output_path}")

Batch processing

from pixopt import optimize_directory
from pixopt.models import OutputFormat

results = optimize_directory(
    "./images",
    "./optimized",
    recursive=True,
    max_width=800,
    quality=75,
    output_format=OutputFormat.WEBP,
)

for r in results:
    if r.success:
        print(f"{r.source_path.name}: {r.savings_percent:.1f}% saved")
    else:
        print(f"{r.source_path.name}: failed — {r.error}")

Format conversion

from pixopt import optimize_image
from pixopt.models import OutputFormat

result = optimize_image(
    "icon.png",
    "icon.webp",
    output_format=OutputFormat.WEBP,
    lossless=True,
)

Lossless compression

from pixopt import optimize_image
from pixopt.models import OutputFormat

result = optimize_image(
    "ui_asset.png",
    "ui_asset.webp",
    output_format=OutputFormat.WEBP,
    lossless=True,
)

Adaptive quality (target file size)

from pixopt import optimize_image
from pixopt.models import OutputFormat

result = optimize_image(
    "photo.jpg",
    "photo_optimized.jpg",
    output_format=OutputFormat.JPEG,
    target_size=50,  # KB
)

Placeholders

from pixopt.placeholder import generate_placeholder

# Dominant color
color = generate_placeholder("photo.jpg", placeholder_type="color")
# → "#3f7a8c"

# Low-quality image placeholder (base64 data URI)
lqip = generate_placeholder("photo.jpg", placeholder_type="lqip")
# → "data:image/jpeg;base64,/9j/4AAQ..."

# Blurhash
blurhash = generate_placeholder("photo.jpg", placeholder_type="blurhash")
# → "LEHV6nWB2yk8pyo0adR*.7kCMdnj"

Smart format detection

from pixopt.smart_format import detect_optimal_format

fmt = detect_optimal_format("photo.jpg")
# Returns OutputFormat.WEBP for photos, PNG for graphics, WEBP for transparent images

Responsive srcset

from pixopt.srcset_generator import generate_srcset_images

variants = generate_srcset_images(
    "hero.jpg",
    "./responsive",
    widths=[320, 640, 1024, 1920],
    output_format="WEBP",
    quality=80,
)

for v in variants:
    print(f"{v.width}px -> {v.size_bytes} bytes")

Backup and min-size filter

from pixopt import optimize_image

result = optimize_image(
    "photo.jpg",
    "photo_optimized.jpg",
    quality=75,
    backup_dir="./backups",
    min_size_bytes=10240,  # Skip files below 10 KB
)

Favicon generation

from pixopt.optimizer import convert_to_favicon

result = convert_to_favicon(
    "logo.png",
    "favicon.ico",
    sizes=[16, 32, 48],
)

---

API Reference

For the complete auto-generated API documentation, visit the official docs.

Key modules:

• pixopt.optimizer — Core optimization functions (optimize_image, optimize_directory, convert_to_favicon)
• pixopt.models — Data models (OptimizationResult, OutputFormat)
• pixopt.placeholder — Placeholder generation (generate_placeholder, extract_dominant_color, generate_lqip_datauri, generate_blurhash)
• pixopt.smart_format — Smart format detection (detect_optimal_format)
• pixopt.srcset_generator — Responsive image generation (generate_srcset_images, SrcsetImage)
• pixopt.adaptive_quality — Adaptive quality (find_quality_for_target_size)
• pixopt.html_comparison — Visual comparison (generate_comparison_html)

---

Development

Install in development mode:

git clone https://github.com/MathiasPaulenko/pixopt.git
cd pixopt
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

Run tests:

pytest tests/ -v

Run linters:

ruff check src tests
mypy src

Build documentation locally:

pip install -e ".[docs]"
mkdocs serve

---

Contributing

We welcome contributions! Please read our Contributing Guide for details on code style, testing, and the pull request workflow.

Quick setup:

git clone https://github.com/MathiasPaulenko/pixopt.git
cd pixopt
pip install -e ".[dev]"
pytest

---

Changelog

See CHANGELOG.md for the full history of changes.

---

License

MIT License — © 2026 pixopt contributors