Registry / serialization / pillow-jxl-plugin

pillow-jxl-plugin

library1.3.7pypypi✓ verified 85d ago

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.

serialization

pip install pillow-jxl-plugin

github ↗package ↗changelog ↗

INSTALL

IMPORT

SIG · PILLOW-JXL-PLUGIN

pillow-jxl-plugin

serializationpythonv1.3.7

Install

2.4s avg

Import

73ms

Disk

51MB

Pass rate

8/ 10

Env Coverage8 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v1.3.7 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✓ —

✓ 2.55s

py 3.11

✓ —

✓ 2.55s

py 3.12

✓ —

✓ 2.15s

py 3.13

✓ —

✓ 2.2s

py 3.9

✕ build_error

51MB installed

● package 51MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

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.

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}")

Debug

Known issues

gotchaInstallation 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.

affects: All versions where pre-built wheels are unavailable.

gotchaMinimum 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.

affects: All versions

gotchaSpecific 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.

affects: All versions, depending on the specific JXL feature or mode.

deprecatedMetadata 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.

affects: <1.3.1

Errors

Common errors & fixes

PIL.UnidentifiedImageError: cannot identify image file 'image.jxl'

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

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

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.

Upgrade

Version history

1.3.7latest on PyPI · released Dec 21, 2025

Audit

Dependencies

PillowrequiredThis library is a plugin for Pillow and requires it to function.

pythonrequiredRequires Python 3.9 or newer.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/Isotr0py/pillow-jpegxl-plugin ↗

packagehttps://pypi.org/project/pillow-jxl-plugin/ ↗

changeloghttps://github.com/Isotr0py/pillow-jpegxl-plugin/releases ↗