Install & Compatibility
Where this runs
tested against v1.9.0 · 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
py 3.11
✕ build_error
4/8 runs
py 3.12
✕ build_error
4/8 runs
py 3.13
✕ build_error
4/8 runs
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
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
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'}")
Debug
Known issues
breakingsimplejpeg is incompatible with NumPy 2.x.x. Projects depending on simplejpeg have been observed pinning NumPy to versions less than 2.0.0.fixPin your `numpy` dependency to `<2.0.0` in your project's `requirements.txt` or `pyproject.toml` (e.g., `numpy<2.0.0`).
affects: All versions up to 1.9.0 when used with numpy>=2.0.0
gotchaBuilding simplejpeg from source on non-supported platforms requires external build dependencies like CMake, nasm, or yasm, which can be difficult to set up.fixEnsure 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.
affects: All versions
gotchaThe `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.fixIf 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)`.
affects: All versions
gotchaPerformance 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.fixWhen 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.
affects: All versions
Errors
Common errors & fixes
TypeError: 'numpy.ndarray' object cannot be interpreted as bytes-like object
Attempting to pass a NumPy array directly to a function expecting raw bytes, or vice-versa, without proper conversion.
fixEnsure 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'
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.
fixVerify `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>
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).
fixEnsure 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)`.
Upgrade
Version history
1.9.0latest on PyPI · released Oct 10, 2025
Audit
Dependencies
numpyrequiredUsed for uncompressed image data (NumPy arrays) in decoding and encoding functions.
libturbojpegrequiredUnderlying C library for JPEG encoding and decoding. Version 3.x is strongly recommended, 2.0.90+ should work, 1.x does not.