image-to-webp

Convert images in almost any format to WebP, from Python or the command line.

• Over 70 input formats with Pillow alone: PNG, JPEG, GIF, BMP, TIFF, ICO/ICNS, TGA, PSD, JPEG 2000, PCX, PPM/PGM/PBM, DDS, SGI, QOI, WebP, …
• More formats through optional installs: HEIC/HEIF/AVIF, camera RAW (CR2, CR3, NEF, ARW, DNG, …) and SVG
• Applies EXIF rotation, keeps transparency, and turns animated GIF/APNG into animated WebP
• Converts files in parallel and writes each output in one step, so a failed run never leaves a half-written file

Install

pip install image-to-webp            # core formats (Pillow only)
pip install "image-to-webp[all]"     # + HEIC/AVIF, RAW and SVG

Requires Python 3.9+.

Library usage

from image_to_webp import convert_file, convert_bytes, convert_image, convert_many, ConversionOptions

# One file -> photo.webp next to it (returns the output Path)
convert_file("photo.heic")
convert_file("photo.png", "out/photo.webp", quality=90)

# In memory
webp_bytes = convert_bytes(png_bytes, lossless=True)
webp_bytes = convert_bytes(open("img.cr2", "rb"), filename="img.cr2")  # filename hints RAW decoding
webp_bytes = convert_image(pil_image, quality=75)

# Reusable settings
opts = ConversionOptions(quality=85, method=6, max_size=(2560, 2560), keep_metadata=True)
convert_file("big.tif", options=opts)

# Batch: files and/or directories, in parallel
summary = convert_many(["images/", "extra.gif"], output_dir="webp", recursive=True,
                       jobs=4, on_result=lambda r: print(r.status, r.src))
print(summary.converted, summary.skipped, summary.failed, summary.bytes_saved)

API reference

**opts accepts the same keywords as ConversionOptions (quality, lossless, method, max_size, keep_metadata). The library never prints. Messages go to Python's logging under the image_to_webp logger.

Command line

image-to-webp photo.jpg                        # -> photo.webp next to source
image-to-webp ./images -r -o ./webp            # recursive, mirror tree into ./webp
image-to-webp *.png --lossless
image-to-webp ./raw -q 85 --max-size 2560x2560 -j 8
image-to-webp ./images -r --dry-run
image-to-webp --list-formats                   # formats + optional plugin status
python -m image_to_webp --help                 # same tool

Exit code is 0 on success, 1 if any file failed, 2 for invalid arguments.

The command is called image-to-webp, not img2webp, because libwebp already ships a tool named img2webp.

Development

./install.sh                    # .venv + editable install with all optional formats + link command to /usr/local/bin (macOS) or /usr/bin
./install.sh --uninstall        # remove the linked command
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest

install.sh uses sudo only when the target directory isn't writable. Override with BIN_DIR=~/.local/bin or CMD_NAME=....

Releasing

1. Update __version__ in src/image_to_webp/__init__.py and CHANGELOG.md.
2. Check the build locally:

   python -m build && python -m twine check --strict dist/*
   

3. Publish:
   • Automated (recommended): set up PyPI trusted publishing for stakmi/image-to-webp with workflow publish.yml and environment pypi, then create a GitHub release tagged v<version>.
   • Manual: python -m twine upload dist/*

License

MIT