Install & Compatibility
Where this runs
tested against v2.5.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
build_error
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 3.7s · import 0.000s · 92MB
93MB installed
● package 93MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
decode
✓ from openjpeg import decode
✗ from pylibjpeg_openjpeg import openjpeg
encode
✓ from openjpeg import encode
✗ from pylibjpeg_openjpeg import openjpeg
decode_pixel_data
✓ from openjpeg import decode_pixel_data
✗ from pylibjpeg_openjpeg import openjpeg
This quickstart demonstrates direct usage of pylibjpeg-openjpeg's `encode_pixel_data` and `decode_pixel_data` functions using NumPy arrays. For DICOM integration, you typically register the plugin with `pylibjpeg` and then use `pylibjpeg.decode()`.
import numpy as np
from pylibjpeg_openjpeg import openjpeg
# Example: Encoding a simple NumPy array to JPEG 2000
# For real use, ensure data matches expected type/shape for J2K
width, height = 128, 128
array_data = np.arange(width * height, dtype=np.uint16).reshape((height, width))
# Encode to JPEG 2000 (lossless example)
encoded_data = openjpeg.encode_pixel_data(
array_data,
bits_allocated=16,
bits_stored=16,
high_bit=15,
photometric_interpretation='MONOCHROME2',
samples_per_pixel=1,
rows=height,
columns=width,
j2k_codec='jp2',
lossless=True
)
print(f"Encoded data length: {len(encoded_data)} bytes")
# Decode the data back
decoded_array, image_format = openjpeg.decode_pixel_data(
encoded_data,
rows=height,
columns=width,
bits_allocated=16,
bits_stored=16,
high_bit=15,
photometric_interpretation='MONOCHROME2',
samples_per_pixel=1
)
print(f"Decoded array shape: {decoded_array.shape}, dtype: {decoded_array.dtype}")
assert np.array_equal(array_data, decoded_array)
print("Original and decoded arrays are equal (lossless encoding verified).")
Debug
Known issues
breakingSupport for Python 3.7 was dropped in v2.0.0, and Python 3.8 was dropped in v2.4.0. Ensure your Python environment is 3.9 or higher.fixUpgrade Python to 3.9 or newer, or use an older pylibjpeg-openjpeg version if tied to an older Python.
affects: >=2.0.0, >=2.4.0
breakingThe `nr_components` parameter in encoding functions was renamed to `samples_per_pixel` in v2.2.0 to align with DICOM terminology.fixUpdate calls to `encode_pixel_data` or `encode_buffer` to use `samples_per_pixel` instead of `nr_components`.
affects: >=2.2.0
breakingAs of v2.4.0, NumPy version 2.0 or higher is required for Python 3.9 and above. For Python 3.8 (supported only in v2.3.0 and older), NumPy < 2.0 was required.fixEnsure your NumPy installation is `numpy>=2.0` if using pylibjpeg-openjpeg v2.4.0+ with Python 3.9+.
affects: >=2.4.0
gotchaUsing `bytearray` as the image data source for encoding functions (`encode_pixel_data()` and `encode_buffer()`) was removed in v2.2.1. Use `bytes` or `numpy.ndarray` instead.fixConvert `bytearray` data to `bytes` or a `numpy.ndarray` before passing it to encoding functions.
affects: >=2.2.1
gotchaFixes were introduced in v2.4.0 for encoding and decoding on big-endian systems, and in v2.5.0 for issues where bits above J2K precision affected encoding results. If experiencing data corruption on big-endian systems or subtle encoding errors, an upgrade is recommended.fixUpgrade to pylibjpeg-openjpeg v2.5.0 or newer to benefit from these fixes.
affects: <2.4.0 (big-endian), <2.5.0 (J2K precision)
Upgrade
Version history
2.5.0latest on PyPI · released Aug 19, 2025
Audit
Dependencies
numpyrequiredRequired for array handling and image data processing.
pylibjpegoptionalThis library is designed as a plugin for pylibjpeg, enabling JPEG 2000 support. Required for its intended integration.