Pillow JPEG-XL Plugin

1.3.7 · active · verified Fri Apr 17

Pillow plugin for adding JPEG-XL (JXL) image format support, leveraging Rust bindings for performance. It seamlessly integrates with Pillow's `Image.open()` and `Image.save()` methods. The library is actively maintained with frequent minor releases, often addressing CI improvements, dependency updates, and adding new JXL features like float16 decode and EXIF support.

Common errors

```
PIL.UnidentifiedImageError: cannot identify image file 'image.jxl'
```
cause The `pillow-jxl-plugin` is not installed, or Pillow cannot discover it. This often happens if the plugin isn't correctly installed in the Python environment Pillow is running in.

fix Ensure `pillow-jxl-plugin` is installed: `pip install pillow-jxl-plugin`. Verify it's installed in the correct environment. Also, confirm the file is a valid JXL image.
```
ERROR: Could not build wheels for pillow-jxl-plugin, which is required to install pyproject.toml-based projects
```
cause This error typically indicates that your system lacks the necessary Rust toolchain to compile the plugin from source. Pre-built wheels are not available for your specific operating system, architecture, or Python version.

fix Install the Rust toolchain by following instructions on `rustup.rs` (e.g., `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`). Ensure your `PATH` includes cargo's bin directory. Alternatively, try upgrading `pip` or using a `manylinux` compatible environment if on Linux.
```
NotImplementedError: JPEG XL image writer does not support mode L
```
cause While `pillow-jxl-plugin` generally supports `L` (grayscale) mode for writing, this specific error indicates an internal issue or a temporary limitation for a particular combination of parameters or JXL features.

fix Try converting the image to a more universally supported mode like `RGB` before saving (`img.convert('RGB').save('output.jxl', ...)`). If the issue persists, ensure you are using the latest version of the plugin and report the specific error with image details to the project's GitHub issues.

Warnings

gotcha Installation issues due to missing Rust toolchain on specific platforms. If pre-built wheels (`.whl` files) are not available for your specific Python version, operating system, and architecture, `pip` will attempt to build the package from source. This requires the Rust compiler and its toolchain to be installed.
Fix: Ensure you have the Rust toolchain installed (e.g., via `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh`) or use a supported environment with pre-built wheels.
gotcha Minimum Python version requirement. `pillow-jxl-plugin` requires Python 3.9 or newer. Installing on older Python versions will fail.
Fix: Ensure your Python environment is 3.9 or newer. Upgrade your Python installation if necessary.
gotcha Specific image modes or JXL features might not be fully supported for decoding or encoding. While common modes like `L`, `RGB`, `RGBA` are supported, advanced JXL features or less common Pillow modes might have limitations.
Fix: Refer to the library's GitHub README or documentation for a list of supported modes and features. If encountering issues, convert the image to a broadly supported mode (e.g., `RGB`) before saving or loading if possible, or report an issue to the maintainers.
deprecated Metadata compression behavior changed. In older versions (e.g., 1.3.1), metadata compression might have been enabled by default or behaved differently. While not a direct breaking API change, it could affect file sizes or metadata integrity if not explicitly controlled.
Fix: For explicit control over metadata compression during saving, use the `metadata_compress` argument (e.g., `img.save('output.jxl', metadata_compress=True/False)`). Check the latest documentation for current defaults and options.

Install

pip install pillow-jxl-plugin Install stable version

Imports

Image
```
from PIL import Image
```
The plugin registers itself automatically with Pillow upon installation. No explicit import of `pillow_jxl` is typically required for basic `Image.open` and `Image.save` operations.

Quickstart

This quickstart demonstrates how to open and save JPEG-XL images using the standard Pillow API. The `pillow-jxl-plugin` integrates directly, so no special JXL-specific functions are called; simply use `Image.open()` and `Image.save()` with `.jxl` file extensions.

from PIL import Image
import os

# Note: pillow-jxl-plugin automatically registers itself upon installation.
# No explicit 'import pillow_jxl' is usually needed.

# Create a dummy image for saving
try:
    dummy_img = Image.new('RGB', (100, 100), color = 'red')
    dummy_img.save('example.jxl', lossless=True, speed=4)
    print("example.jxl created successfully.")

    # Open a JPEG-XL image
    img = Image.open('example.jxl')
    print(f"Opened JXL image: {img.format}, mode={img.mode}, size={img.size}")

    # Convert to another format and save (optional)
    img.convert('RGB').save('example.png')
    print("example.png saved.")

    # Clean up (optional)
    os.remove('example.jxl')
    os.remove('example.png')
    print("Cleaned up example files.")

except FileNotFoundError:
    print("Make sure 'example.jxl' (or another JXL file) exists in the current directory if you want to test opening a pre-existing one.")
except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →