{"id":10039,"library":"pillow-jxl-plugin","title":"Pillow JPEG-XL Plugin","description":"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.","status":"active","version":"1.3.7","language":"en","source_language":"en","source_url":"https://github.com/Isotr0py/pillow-jpegxl-plugin","tags":["Pillow","Image Processing","JPEG-XL","JXL","Image Codec","Rust","Plugin"],"install":[{"cmd":"pip install pillow-jxl-plugin","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"This library is a plugin for Pillow and requires it to function.","package":"Pillow","optional":false},{"reason":"Requires Python 3.9 or newer.","package":"python","optional":false}],"imports":[{"note":"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.","symbol":"Image","correct":"from PIL import Image"}],"quickstart":{"code":"from PIL import Image\nimport os\n\n# Note: pillow-jxl-plugin automatically registers itself upon installation.\n# No explicit 'import pillow_jxl' is usually needed.\n\n# Create a dummy image for saving\ntry:\n    dummy_img = Image.new('RGB', (100, 100), color = 'red')\n    dummy_img.save('example.jxl', lossless=True, speed=4)\n    print(\"example.jxl created successfully.\")\n\n    # Open a JPEG-XL image\n    img = Image.open('example.jxl')\n    print(f\"Opened JXL image: {img.format}, mode={img.mode}, size={img.size}\")\n\n    # Convert to another format and save (optional)\n    img.convert('RGB').save('example.png')\n    print(\"example.png saved.\")\n\n    # Clean up (optional)\n    os.remove('example.jxl')\n    os.remove('example.png')\n    print(\"Cleaned up example files.\")\n\nexcept FileNotFoundError:\n    print(\"Make sure 'example.jxl' (or another JXL file) exists in the current directory if you want to test opening a pre-existing one.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions where pre-built wheels are unavailable."},{"fix":"Ensure your Python environment is 3.9 or newer. Upgrade your Python installation if necessary.","message":"Minimum Python version requirement. `pillow-jxl-plugin` requires Python 3.9 or newer. Installing on older Python versions will fail.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, depending on the specific JXL feature or mode."},{"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.","message":"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.","severity":"deprecated","affected_versions":"<1.3.1"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","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.","error":"PIL.UnidentifiedImageError: cannot identify image file 'image.jxl'"},{"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.","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.","error":"ERROR: Could not build wheels for pillow-jxl-plugin, which is required to install pyproject.toml-based projects"},{"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.","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.","error":"NotImplementedError: JPEG XL image writer does not support mode L"}]}