simplejpeg

Common errors

• TypeError: 'numpy.ndarray' object cannot be interpreted as bytes-like object

  cause Attempting to pass a NumPy array directly to a function expecting raw bytes, or vice-versa, without proper conversion.
  fix Ensure that `encode_jpeg` receives a NumPy array and `decode_jpeg` receives bytes-like object (e.g., `bytes`, `bytearray`, `memoryview`). If you have a NumPy array that you want to treat as bytes, you might need to convert it or use its buffer interface if the function supports it. `simplejpeg` functions typically handle this correctly, so check the input type to the `simplejpeg` calls specifically.

• ImportError: cannot import name 'decode_jpeg' from 'simplejpeg'

  cause The `simplejpeg` package or its underlying C extensions were not installed correctly, or there's a Python environment issue preventing the module from being found.
  fix Verify `simplejpeg` is installed by running `pip list`. If present, try reinstalling with `pip install --force-reinstall simplejpeg`. If building from source, ensure `cmake`, `nasm`, or `yasm` are correctly installed and configured in your system environment path. Also, check Python version compatibility (>=3.9).

• ValueError: JPEG data error: <some error message from libturbojpeg>

  cause The input data provided to `decode_jpeg` or `decode_jpeg_header` is not valid JPEG data, or contains errors that `libturbojpeg` cannot recover from, especially when `strict=True` (default).
  fix Ensure the input `bytes` object contains valid JPEG (JFIF) data. If the error persists for slightly corrupted images, try setting `strict=False` in the decoding function calls to allow for recoverable errors: `decoded_image = decode_jpeg(jpeg_data, strict=False)`.

Warnings

• breaking simplejpeg is incompatible with NumPy 2.x.x. Projects depending on simplejpeg have been observed pinning NumPy to versions less than 2.0.0.
  Fix: Pin your `numpy` dependency to `<2.0.0` in your project's `requirements.txt` or `pyproject.toml` (e.g., `numpy<2.0.0`).
• gotcha Building simplejpeg from source on non-supported platforms requires external build dependencies like CMake, nasm, or yasm, which can be difficult to set up.
  Fix: Ensure your system has `cmake` and either `nasm` or `yasm` installed before attempting to `pip install simplejpeg` without pre-built wheels. Refer to the `libturbojpeg` documentation for specific system requirements.
• gotcha The `strict` parameter in `decode_jpeg` and `decode_jpeg_header` defaults to `True`. This will cause `ValueError` to be raised for recoverable errors in the JPEG data, which might halt processing of slightly malformed images.
  Fix: If you need to process JPEG data that might contain minor, recoverable errors, set `strict=False` in your `decode_jpeg` or `decode_jpeg_header` calls. Example: `decoded_image = decode_jpeg(jpeg_data, strict=False)`.
• gotcha Performance comparison with other libraries like OpenCV can be misleading if not tested under realistic conditions. Randomly generated images often have high-frequency content that challenges JPEG encoders differently than natural images.
  Fix: When benchmarking `simplejpeg` against other libraries, use a diverse set of real-world images and ensure consistent quality settings and input/output formats (e.g., encoding without saving to disk) to get accurate performance metrics relevant to your use case.

Install

• pip install simplejpeg Stable release on supported platforms
• pip install simplejpeg --no-binary :all: From source (requires build tools)

Imports

• decode_jpeg

  from simplejpeg import decode_jpeg

• encode_jpeg

  from simplejpeg import encode_jpeg

• decode_jpeg_header

  from simplejpeg import decode_jpeg_header

• is_jpeg

  from simplejpeg import is_jpeg

Quickstart

This quickstart demonstrates encoding a NumPy array representing an RGB image into JPEG bytes, and then decoding those bytes back into a NumPy array using simplejpeg. It also includes a check for JPEG header information.

import numpy as np
from simplejpeg import encode_jpeg, decode_jpeg

# 1. Create a dummy RGB image (NumPy array)
width, height = 640, 480
image_data_rgb = np.random.randint(0, 256, (height, width, 3), dtype=np.uint8)

# 2. Encode the image to JPEG bytes
jpeg_bytes = encode_jpeg(image_data_rgb, quality=85, colorspace='RGB')
print(f"Encoded JPEG size: {len(jpeg_bytes)} bytes")

# 3. Decode the JPEG bytes back to a NumPy array
decoded_image_rgb = decode_jpeg(jpeg_bytes, colorspace='RGB')
print(f"Decoded image shape: {decided_image_rgb.shape}")

# Optional: Check if the data is a JPEG
is_it_jpeg = decode_jpeg_header(jpeg_bytes)
print(f"Is the data a JPEG? {'Yes' if is_it_jpeg else 'No'}")