picx-image-optimizer 0.1.1

A tiny Python image optimization toolkit for batch compression and web assets.

picx

picx is a small Python image optimization package for web assets, blogs, avatars, and batch cleanup jobs. The package installs a CLI named picx and exposes a compact Python API under picx.

Features

• Compress single images or entire directories.
• Convert between jpg, png, webp, avif, and tiff outputs.
• Read jpg, jpeg, png, webp, avif, tif, and tiff inputs.
• Resize with max_width and max_height.
• Strip image metadata by default.
• Search for the highest quality under a target byte size.
• Render CLI compression reports with Rich.
• Use web, blog, avatar, and lossless presets.

Install

Install from PyPI:

pip install picx-image-optimizer

Install from source:

git clone https://github.com/ingeniousfrog/picx.git
cd picx
pip install .

For local development:

pip install -e ".[dev]"

pip install picx-image-optimizer installs the pyvips Python backend package. pyvips also needs the native libvips system library for large-image processing. pip cannot install this native system library for every platform, so install it once with your OS or environment package manager:

brew install vips
# or
conda install -c conda-forge libvips pyvips

Install libvips in the same environment that runs picx. For example, if you run picx inside conda activate comfyui, install libvips inside that conda environment. Mixing Homebrew libvips with Anaconda/conda libraries can still fail on macOS with dynamic-library or code-signature errors.

CLI

Optimize one image:

picx image ./photo.png --output ./dist/photo.webp --format webp --quality 82

Optimize a directory recursively while preserving relative paths:

picx dir ./images ./out --format webp --preset web

Try a target size in bytes:

picx image ./hero.jpg --output ./out/hero.webp --format webp --target-size 120000

Handle trusted large images with Pillow:

picx image ./texture.tif --output ./texture.webp --format webp --allow-large --max-pixels 400000000

Use the pyvips backend for large images:

picx image ./texture.tif --output ./texture.webp --format webp --backend pyvips

WebP has a per-side dimension limit of 16383 pixels. If either width or height is larger, resize first or use tiling:

picx image ./texture.tif --output ./texture.webp --format webp --backend pyvips --max-height 16000

Create tiles and a manifest for very large images:

picx tile ./texture.tif ./tiles --tile-size 1024 --format webp

Python API

from picx import optimize_dir, optimize_image, tile_image

single = optimize_image(
    "photo.png",
    output="dist/photo.webp",
    format="webp",
    quality=82,
    max_width=1600,
    strip_meta=True,
)

batch = optimize_dir(
    "images",
    "out",
    format="webp",
    preset="blog",
    recursive=True,
)

tiles = tile_image("texture.tif", "tiles", tile_size=1024, format="webp")

optimize_image() and optimize_dir() return OptimizeResult objects with:

• original_size
• output_size
• savings_ratio
• skipped
• error
• source_path
• output_path

Presets

Preset	Output	Purpose
web	webp, quality 82, max width 1920	General website images
blog	webp, quality 78, max width 1600	Blog and article images
avatar	webp, quality 85, max 256 x 256	Profile images
lossless	png, quality 100	Lossless-ish cleanup with metadata stripping

Development

python3 -m pytest

picx uses Pillow by default and includes the pyvips Python backend package. The pyvips backend also requires the native libvips system library, which pip does not install automatically. Install libvips in the same environment that runs picx.

Large Images

By default, picx keeps Pillow's large-image safety posture. If an image exceeds the configured pixel limit, picx reports a clear error with next steps instead of showing a raw traceback. For trusted images, use --allow-large and optionally set --max-pixels. For memory-efficient processing, install system libvips and select --backend pyvips or keep the default --backend auto.

For single-file WebP output, keep both width and height at or below 16383 pixels. Images larger than that should be resized with --max-width / --max-height, or exported with picx tile instead.

picx tile writes image tiles plus manifest.json. The manifest is an index, not a merged image: it records the original size, tile size, output format, levels, and every tile's path and coordinates so another tool can display or reconstruct the tile layout reliably.