WebP Image Conversion and Manipulation

0.4.0 · active · verified Fri Apr 17

The `webp` library provides Python bindings for `libwebp`, enabling encoding, decoding, reading, and saving of WebP images. It integrates seamlessly with Pillow (PIL) for image manipulation, making it easy to convert between various image formats and WebP. The library is actively maintained with regular updates, typically bundling the latest `libwebp` version to ensure security and performance. Current version is 0.4.0.

Common errors

```
ModuleNotFoundError: No module named 'webp._webp'
```
cause Attempting to import from the internal `_webp` module directly, whose path changed in version 0.4.0 and is not intended for direct use.

fix Use the public API functions directly from the `webp` package, e.g., `from webp import imencode`.
```
webp.WebPError: failed to encode image
```
cause The input image data is invalid, corrupted, or incompatible with WebP encoding parameters (e.g., incorrect Pillow image mode for the requested encoding type).

fix Verify the input image is a valid Pillow `Image.Image` object and ensure its mode (e.g., 'RGB', 'RGBA') is suitable for the WebP parameters provided. Check logs for more specific `libwebp` errors if available.
```
error: command 'gcc' failed with exit status 1
```
cause During `pip install webp`, if a pre-built binary wheel is not available for your system (OS, architecture, Python version), the package attempts to compile `libwebp` from source. This requires a C compiler (like `gcc`) and `libwebp` development headers to be installed on your system.

fix Install a C compiler and `libwebp` development headers. On Debian/Ubuntu: `sudo apt-get update && sudo apt-get install build-essential libwebp-dev`. On Fedora: `sudo dnf install @development-tools libwebp-devel`. On macOS: `xcode-select --install` and `brew install webp`.

Warnings

gotcha When compressing images using the `target_size` option, you must set `passes` to a value greater than 1 (e.g., `passes=2`). If `passes` is not specified or set to 1, `target_size` will be ignored, resulting in a potentially larger output file than intended.
Fix: Ensure `passes` is set to a value like `2` or higher when using `target_size`: `webp.imencode(img, target_size=100_000, passes=2)`.
breaking Versions of `webp` prior to 0.3.0 bundled `libwebp 1.0.3`, which has a known vulnerability (CVE-2023-4863) related to heap buffer overflow. While the Python API remains compatible, not upgrading poses a significant security risk.
Fix: Upgrade to `webp>=0.3.0` immediately to patch the `libwebp` vulnerability: `pip install --upgrade webp`.
gotcha In version 0.4.0, the internal `_webp` module was nested within the `webp` package. Any direct imports like `from webp._webp import ...` will fail, as this module is not part of the public API and its path changed.
Fix: Always use the public API functions directly from the `webp` package (e.g., `from webp import imencode, imdecode, imread, imsave`).

Install

pip install webp Install webp

Imports

imencode
```
from webp import imencode
```
imdecode
```
from webp import imdecode
```
imread
```
from webp import imread
```
imsave
```
from webp import imsave
```

Quickstart

This example demonstrates how to create a simple Pillow image, encode it into WebP format bytes, and then decode those bytes back into a Pillow image using the `webp` library's `imencode` and `imdecode` functions.

from PIL import Image
import webp
import io

# Create a dummy image using Pillow
img = Image.new('RGB', (100, 100), color = 'red')

# Encode image to WebP bytes with quality 80
webp_bytes = webp.imencode(img, quality=80)
print(f"Encoded WebP image size: {len(webp_bytes)} bytes")

# Decode WebP bytes back into a Pillow Image
decoded_img = webp.imdecode(webp_bytes)
print(f"Decoded image mode: {decoded_img.mode}, size: {decoded_img.size}")

# Optionally save to a file (replace 'output.webp' with desired path)
# webp.imsave('output.webp', decoded_img, quality=80)

# Example of reading directly from a file (if you had one)
# loaded_img = webp.imread('path/to/image.webp')

view raw JSON →