Install & Compatibility
Where this runs
tested against v2.1.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
87MB installed
● package 87MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
decode
✓ from pylibjpeg import decode
✗ import pylibjpeg; pylibjpeg.add_handler(...)
debug_logger
✓ from pylibjpeg import debug_logger
logging
✓ from pylibjpeg import logging
This quickstart demonstrates how to install `pylibjpeg` and its necessary backend handlers, then registers them with the `pydicom` library to enable decoding of compressed DICOM pixel data (JPEG, RLE). You must install the `pylibjpeg-libjpeg` and/or `pylibjpeg-rle` packages separately to enable their respective decoding capabilities. The `DICOM_FILE_PATH` environment variable can be set to point to a test DICOM file.
import pydicom
import pylibjpeg
import os
# Ensure you have installed a backend, e.g., 'pip install pylibjpeg-libjpeg'
# and optionally 'pip install pylibjpeg-rle' for RLE support.
try:
import pylibjpeg_libjpeg
# Register the JPEG handler. For pydicom, registering the top-level package
# automatically adds all handlers within it.
pylibjpeg.add_handler(pylibjpeg_libjpeg)
print("pylibjpeg_libjpeg handler successfully added.")
except ImportError:
print("Warning: pylibjpeg-libjpeg is not installed. JPEG decoding will not be available.")
try:
import pylibjpeg_rle
pylibjpeg.add_handler(pylibjpeg_rle)
print("pylibjpeg_rle handler successfully added.")
except ImportError:
print("Warning: pylibjpeg-rle is not installed. RLE decoding/encoding will not be available.")
print(f"Current active pylibjpeg handlers: {pylibjpeg.get_handlers()}")
# Example: Decode a DICOM file using pydicom (requires a valid DICOM file)
# Set DICOM_FILE_PATH environment variable for testing, e.g., an image with JPEG/RLE compression
dicom_file_path = os.environ.get('DICOM_FILE_PATH', 'path/to/your/compressed_dicom.dcm')
if os.path.exists(dicom_file_path):
try:
ds = pydicom.dcmread(dicom_file_path)
if hasattr(ds, 'pixel_array'):
pixel_array = ds.pixel_array
print(f"Successfully decoded pixel data from '{dicom_file_path}' with shape: {pixel_array.shape}")
else:
print(f"DICOM file '{dicom_file_path}' does not contain pixel data or could not be decoded by available handlers.")
except Exception as e:
print(f"Error reading DICOM file or decoding pixel data: {e}")
else:
print(f"Skipping DICOM decode example: DICOM_FILE_PATH '{dicom_file_path}' not found or not set.")
Debug
Known issues
breakingVersion 2.0.0 introduced a major rewrite of the handler API and moved core decoder modules into separate packages. Direct imports like `pylibjpeg.libjpeg` or `pylibjpeg.rle` are no longer valid and will cause `AttributeError`.fixInstall `pylibjpeg-libjpeg` and `pylibjpeg-rle` as separate packages (`pip install pylibjpeg-libjpeg pylibjpeg-rle`), then use `import pylibjpeg_libjpeg` and `import pylibjpeg_rle` for registration, e.g., `pylibjpeg.add_handler(pylibjpeg_libjpeg)`.
affects: >=2.0.0
gotchaInstalling `pylibjpeg` alone does not provide any JPEG or RLE decoding capabilities. `pylibjpeg` is a framework; you must also install at least one backend package (e.g., `pylibjpeg-libjpeg` for JPEG, `pylibjpeg-rle` for RLE) and register its handler(s).fixAfter `pip install pylibjpeg`, also install `pip install pylibjpeg-libjpeg` and/or `pip install pylibjpeg-rle`, then register them in your code: `pylibjpeg.add_handler(pylibjpeg_libjpeg)`.
affects: All versions
gotchaIf `pydicom` reports `RuntimeError: No pixel data handler could be found for transfer syntax ...`, it's likely that `pylibjpeg` is installed but the necessary backend handler for the specific compression (e.g., JPEG, RLE) was not installed or not registered via `pylibjpeg.add_handler()`.fixEnsure you have installed the correct backend package (`pylibjpeg-libjpeg` or `pylibjpeg-rle`) and have called `pylibjpeg.add_handler()` with the imported backend module before attempting to read compressed DICOM pixel data.
affects: All versions when used with pydicom
Upgrade
Version history
2.1.0latest on PyPI · released Sep 1, 2025
Audit
Dependencies
numpyrequiredRequired for internal image data processing and array manipulation.
pylibjpeg-libjpegoptionalProvides the actual JPEG image decoding backend; required for JPEG functionality.
pylibjpeg-rleoptionalProvides the actual DICOM RLE decoding/encoding backend; required for RLE functionality.