Install & Compatibility
Where this runs
tested against v2.2.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
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 90.8MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 4.7s · import 0.000s · 87MB
90MB installed
● package 90MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
TurboJPEG
✓ from turbojpeg import TurboJPEG
✗ from pyturbojpeg import TurboJPEG
This quickstart demonstrates how to initialize PyTurboJPEG, create a dummy image (using NumPy), encode it into JPEG format, and then decode the JPEG data back into a raw pixel buffer, converting it back to a NumPy array for further processing. It includes error handling guidance for common issues related to the libjpeg-turbo dependency.
from pyturbojpeg import TurboJPEG, TJPF_BGR, TJ_BGR
import numpy as np
import os
# Instantiate TurboJPEG. Optionally, pass the path to libturbojpeg.so.0, .dylib, or .dll
# Example: jpeg = TurboJPEG('/usr/local/lib/libturbojpeg.so.0')
jpeg = TurboJPEG()
# --- Encode Example ---
# Create a dummy BGR image (e.g., from OpenCV or Pillow in BGR mode)
width, height = 640, 480
# For simplicity, create a blank image; in real use, this would be actual image data
# PyTurboJPEG expects contiguous C-style arrays for input
dummy_img_array = np.zeros((height, width, 3), dtype=np.uint8)
# Set a pixel to demonstrate it's not entirely blank, just to ensure data is there
dummy_img_array[50, 50] = [255, 0, 0] # Blue pixel
# Encode the NumPy array (its byte representation) to JPEG
# TJPF_BGR indicates the input pixel format
try:
jpeg_data = jpeg.encode(dummy_img_array.tobytes(), width, height, TJPF_BGR, quality=85)
print(f"Successfully encoded JPEG data. Size: {len(jpeg_data)} bytes")
# Save to a file for verification (optional)
# with open('output.jpg', 'wb') as f:
# f.write(jpeg_data)
# --- Decode Example ---
# Decode the JPEG data back to raw pixel data
# TJ_BGR indicates the desired output colorspace (constant for BGR output)
decoded_image_data, decoded_width, decoded_height, decoded_pix_fmt, decoded_colorspace = \
jpeg.decode(jpeg_data, TJ_BGR)
print(f"Decoded image: {decoded_width}x{decoded_height}, "
f"Pixel Format: {decoded_pix_fmt}, Colorspace: {decoded_colorspace}")
# Convert decoded raw data back to a NumPy array
decoded_array = np.frombuffer(decoded_image_data, dtype=np.uint8).reshape((decoded_height, decoded_width, 3))
print(f"Decoded NumPy array shape: {decoded_array.shape}")
except Exception as e:
print(f"An error occurred: {e}")
print("Please ensure libjpeg-turbo is correctly installed and discoverable by PyTurboJPEG.")
print("You might need to set LD_LIBRARY_PATH (Linux), DYLD_LIBRARY_PATH (macOS), or PATH (Windows).")
print("Alternatively, explicitly pass the library path to TurboJPEG() constructor.")
Debug
Known issues
breakingVersion 2.0.0 migrated to the TurboJPEG 3.1.x function-based API. While the Python `TurboJPEG` class structure remains similar, underlying C API changes might lead to `TypeError` or `ValueError` if specific (especially low-level or less common) parameters or flag combinations from pre-2.0.0 versions are used.fixReview your `encode()` and `decode()` calls against the latest PyTurboJPEG documentation. Pay attention to changes in parameter names, expected types, or available flags. If encountering `TypeError` or `ValueError`, consult the source code or latest README for argument signatures.
affects: >=2.0.0
gotchaPyTurboJPEG is a wrapper library and requires the native `libjpeg-turbo` shared library (e.g., `libturbojpeg.so.0` on Linux, `libturbojpeg.dylib` on macOS, `turbojpeg.dll` on Windows) to be installed on your system. Without it, PyTurboJPEG cannot function and will raise an `OSError`.fixInstall `libjpeg-turbo` via your system's package manager (e.g., `sudo apt-get install libturbojpeg0` on Debian/Ubuntu, `brew install libjpeg-turbo` on macOS) or download binaries. Ensure the library's path is discoverable by your system's dynamic linker (e.g., set `LD_LIBRARY_PATH` on Linux, `DYLD_LIBRARY_PATH` on macOS, or `PATH` on Windows) or explicitly pass the full path to the `TurboJPEG()` constructor: `jpeg = TurboJPEG('/path/to/libturbojpeg.so')`. affects: All versions
gotchaPyTurboJPEG's performance benefits are maximized with `numpy` arrays, but it expects input buffers (e.g., from `numpy.ndarray.tobytes()`) to be C-contiguous. If you pass a non-contiguous array, it may result in incorrect output or errors.fixEnsure your NumPy arrays are C-contiguous before passing them to `encode()` or `decode()`. Use `.copy(order='C')` if necessary, e.g., `img_array.copy(order='C').tobytes()`. Version 1.7.5 introduced internal checks to ensure contiguous arrays.
affects: <1.7.5 (potential issues), All versions (best practice)
gotchaVersions 2.1.0 and newer introduce support for 12-bit and 16-bit precision JPEGs, as well as lossless JPEG. If your application previously only handled 8-bit standard JPEGs, ensure your decoding and encoding pipelines explicitly manage precision settings if you encounter these new formats, to avoid unexpected truncation or errors.fixBe aware of new constants and parameters related to precision (e.g., `TJ_PRECISION_12`, `TJ_PRECISION_16`) and lossless options. Consult the documentation for specific API calls if working with non-8-bit or lossless JPEGs.
affects: >=2.1.0
Upgrade
Version history
2.2.0latest on PyPI · released Feb 21, 2026
Audit
Dependencies
No dependency data recorded yet.