{"id":8643,"library":"simplejpeg","title":"simplejpeg","description":"simplejpeg is a Python library offering fast JPEG encoding and decoding, built upon recent versions of libturbojpeg. It targets use cases prioritizing speed and direct memory access over broader image format support. The library is actively maintained with regular releases, currently at version 1.9.0, providing efficient handling of JPEG images as NumPy arrays.","status":"active","version":"1.9.0","language":"en","source_language":"en","source_url":"https://github.com/jfolz/simplejpeg","tags":["image processing","jpeg","encoding","decoding","numpy","performance"],"install":[{"cmd":"pip install simplejpeg","lang":"bash","label":"Stable release on supported platforms"},{"cmd":"pip install simplejpeg --no-binary :all:","lang":"bash","note":"On unsupported platforms (e.g., specific Linux distributions or architectures without pre-built wheels), or if pip attempts to build from source, you will need `cmake`, and either `nasm` or `yasm` installed on your system.","label":"From source (requires build tools)"}],"dependencies":[{"reason":"Used for uncompressed image data (NumPy arrays) in decoding and encoding functions.","package":"numpy","optional":false},{"reason":"Underlying C library for JPEG encoding and decoding. Version 3.x is strongly recommended, 2.0.90+ should work, 1.x does not.","package":"libturbojpeg","optional":false}],"imports":[{"symbol":"decode_jpeg","correct":"from simplejpeg import decode_jpeg"},{"symbol":"encode_jpeg","correct":"from simplejpeg import encode_jpeg"},{"symbol":"decode_jpeg_header","correct":"from simplejpeg import decode_jpeg_header"},{"symbol":"is_jpeg","correct":"from simplejpeg import is_jpeg"}],"quickstart":{"code":"import numpy as np\nfrom simplejpeg import encode_jpeg, decode_jpeg\n\n# 1. Create a dummy RGB image (NumPy array)\nwidth, height = 640, 480\nimage_data_rgb = np.random.randint(0, 256, (height, width, 3), dtype=np.uint8)\n\n# 2. Encode the image to JPEG bytes\njpeg_bytes = encode_jpeg(image_data_rgb, quality=85, colorspace='RGB')\nprint(f\"Encoded JPEG size: {len(jpeg_bytes)} bytes\")\n\n# 3. Decode the JPEG bytes back to a NumPy array\ndecoded_image_rgb = decode_jpeg(jpeg_bytes, colorspace='RGB')\nprint(f\"Decoded image shape: {decided_image_rgb.shape}\")\n\n# Optional: Check if the data is a JPEG\nis_it_jpeg = decode_jpeg_header(jpeg_bytes)\nprint(f\"Is the data a JPEG? {'Yes' if is_it_jpeg else 'No'}\")","lang":"python","description":"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."},"warnings":[{"fix":"Pin your `numpy` dependency to `<2.0.0` in your project's `requirements.txt` or `pyproject.toml` (e.g., `numpy<2.0.0`).","message":"simplejpeg is incompatible with NumPy 2.x.x. Projects depending on simplejpeg have been observed pinning NumPy to versions less than 2.0.0.","severity":"breaking","affected_versions":"All versions up to 1.9.0 when used with numpy>=2.0.0"},{"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.","message":"Building simplejpeg from source on non-supported platforms requires external build dependencies like CMake, nasm, or yasm, which can be difficult to set up.","severity":"gotcha","affected_versions":"All versions"},{"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)`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"Attempting to pass a NumPy array directly to a function expecting raw bytes, or vice-versa, without proper conversion.","error":"TypeError: 'numpy.ndarray' object cannot be interpreted as bytes-like object"},{"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).","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.","error":"ImportError: cannot import name 'decode_jpeg' from 'simplejpeg'"},{"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)`.","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).","error":"ValueError: JPEG data error: <some error message from libturbojpeg>"}]}