Registry / serialization / pylibjpeg-libjpeg

pylibjpeg-libjpeg

library2.4.0pypypi✓ verified 88d ago

pylibjpeg-libjpeg is a Python wrapper for the `libjpeg` C library, designed primarily to function as a plugin for the `pylibjpeg` framework, which in turn provides JPEG decoding capabilities for `pydicom`. It enables Python applications to decode various JPEG formats, including JPEG Baseline, Extended, Lossless (Process 14), JPEG-LS Lossless, and Lossy. The library is actively maintained, with the current version being 2.4.0, and typically sees updates for Python version compatibility and `libjpeg` upgrades every few months to a year.

serialization data http-networking

pip install pylibjpeg-libjpeg

github ↗package ↗

INSTALL

IMPORT

SIG · PYLIBJPEG-LIBJPEG

pylibjpeg-libjpeg

serializationpythonv2.4.0

Install

4.1s avg

Import

350ms

Disk

99MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.4.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

musl

py 3.10–3.920 runs

build_error

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 4.1s · import 0.350s · 98MB

99MB installed

● package 99MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

decode

✓ from libjpeg import decode

For standalone JPEG image decoding to a NumPy array without pydicom.

pydicom

✓ import pydicom

When used as a pydicom plugin, pylibjpeg-libjpeg is implicitly loaded, so no direct import is usually needed for plugin functionality. Just ensure it's installed alongside pydicom and pylibjpeg.

This quickstart demonstrates the primary use case of `pylibjpeg-libjpeg` as a plugin for `pydicom` to decode JPEG-compressed DICOM pixel data. Once installed, `pydicom` (via `pylibjpeg`) automatically discovers and uses `pylibjpeg-libjpeg` for supported JPEG transfer syntaxes.

import pydicom from pydicom.data import get_testdata_file import numpy # pylibjpeg-libjpeg returns numpy arrays # Ensure pylibjpeg-libjpeg is installed: pip install pylibjpeg-libjpeg # This makes it available as a plugin for pydicom through pylibjpeg # Load a DICOM file with JPEG-compressed pixel data # Requires 'pydicom-data' for test files, or use your own DICOM file # If you don't have test files, uncomment: pydicom.data.fetch_data_files() dicom_file_path = get_testdata_file('JPEG-LL.dcm') # Example: JPEG Lossless ds = pydicom.dcmread(dicom_file_path) # Accessing .pixel_array will trigger decoding via pylibjpeg-libjpeg # if the transfer syntax is supported by the plugin. pixel_array = ds.pixel_array print(f"DICOM file loaded: {dicom_file_path}") print(f"Transfer Syntax UID: {ds.file_meta.TransferSyntaxUID}") print(f"Pixel array shape: {pixel_array.shape}") print(f"Pixel array dtype: {pixel_array.dtype}") print(f"Type of decoded data: {type(pixel_array)}")

Debug

Known issues

breakingPython 3.9 support was removed in v2.4.0. Python 3.7 support was dropped in v2.0.0. Always verify your Python version compatibility with the installed `pylibjpeg-libjpeg` version.

fix

Upgrade to a supported Python version (currently >=3.10 and <4.0).

affects: >=2.0.0, >=2.4.0

breakingNumPy version requirements changed significantly: v2.3.0 and newer generally require NumPy 2.0+. Older versions (e.g., Python 3.8 with v2.2.0) explicitly required NumPy < 2.0.

fix

Ensure your NumPy version matches the requirements of your `pylibjpeg-libjpeg` and Python version. For `pylibjpeg-libjpeg` v2.3.0+, install `numpy>=2.0.0`.

affects: >=2.2.0

deprecatedThe `utils.reconstruct()` function was removed in v2.0.0.

fix

Migrate any code using `utils.reconstruct()` to an alternative approach, likely involving direct pixel array manipulation with NumPy.

affects: >=2.0.0

gotchaEncoding of JPEG images is not currently supported by `pylibjpeg-libjpeg`; it is a decoding-only library.

fix

Use other libraries if JPEG encoding functionality is required.

affects: All versions

gotchaVersion 2.3.0 introduced changes to ensure consistency in the endianness of decoded data on big-endian systems. This may subtly affect pixel data interpretation for users on such architectures upgrading from older versions.

fix

Review image processing pipelines for potential endianness-related side effects if upgrading on a big-endian system.

affects: >=2.3.0

Errors

Common errors & fixes

RuntimeError: Unable to convert the Pixel Data as the 'pylibjpeg-libjpeg' plugin is not installed

This error typically occurs when pydicom (or pylibjpeg) attempts to decode JPEG pixel data but cannot find or load the pylibjpeg-libjpeg plugin. This can be due to the plugin not being installed, an incorrect Python environment, or platform-specific wheel issues.

fix

Ensure `pylibjpeg-libjpeg` is correctly installed in the active Python environment (`pip install pylibjpeg-libjpeg`). Verify that a compatible wheel is available for your OS and Python version.

PyInstaller/cx_Freeze fails to bundle or find 'pylibjpeg-libjpeg' in executable: 'No module named 'pylibjpeg-libjpeg' or GDCM handler error.

Executable creators like PyInstaller or cx_Freeze may have difficulty finding and bundling the underlying C library or `pkg_resources` entry points used by `pylibjpeg-libjpeg`.

fix

For PyInstaller, you might need to manually include `pylibjpeg-libjpeg` (and `libjpeg`) as hidden imports or provide custom hooks to ensure it's properly packaged. Consult PyInstaller's documentation on handling plugins and C extensions.

AttributeError: partially initialized module 'pydicom' has no attribute 'config' (most likely due to a circular import)

This can occur due to circular import issues between pydicom and pylibjpeg components, often seen when trying to install development versions or with certain combinations of pydicom/pylibjpeg/pylibjpeg-libjpeg.

fix

Ensure all pydicom-related libraries (pydicom, pylibjpeg, pylibjpeg-libjpeg) are installed from stable releases. If trying development versions, perform a clean uninstall of all components before reinstalling.

Upgrade

Version history

2.4.0latest on PyPI · released Mar 7, 2026

Audit

Dependencies

numpyrequiredRequired for array manipulation and pixel data representation.

pylibjpegrequiredpylibjpeg-libjpeg acts as a plugin for the pylibjpeg framework, which is often used with pydicom.

Agent activity

13 hits · last 30 days

node

Resources

githubhttps://github.com/pydicom/pylibjpeg-libjpeg ↗

packagehttps://pypi.org/project/pylibjpeg-libjpeg/ ↗