{"id":8495,"library":"pylibjpeg-libjpeg","title":"pylibjpeg-libjpeg","description":"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.","status":"active","version":"2.4.0","language":"en","source_language":"en","source_url":"https://github.com/pydicom/pylibjpeg-libjpeg","tags":["jpeg","dicom","image-processing","libjpeg","pydicom","medical-imaging"],"install":[{"cmd":"pip install pylibjpeg-libjpeg","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Required for array manipulation and pixel data representation.","package":"numpy","optional":false},{"reason":"pylibjpeg-libjpeg acts as a plugin for the pylibjpeg framework, which is often used with pydicom.","package":"pylibjpeg","optional":false}],"imports":[{"note":"For standalone JPEG image decoding to a NumPy array without pydicom.","symbol":"decode","correct":"from libjpeg import decode"},{"note":"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.","symbol":"pydicom","correct":"import pydicom"}],"quickstart":{"code":"import pydicom\nfrom pydicom.data import get_testdata_file\nimport numpy # pylibjpeg-libjpeg returns numpy arrays\n\n# Ensure pylibjpeg-libjpeg is installed: pip install pylibjpeg-libjpeg\n# This makes it available as a plugin for pydicom through pylibjpeg\n\n# Load a DICOM file with JPEG-compressed pixel data\n# Requires 'pydicom-data' for test files, or use your own DICOM file\n# If you don't have test files, uncomment: pydicom.data.fetch_data_files()\ndicom_file_path = get_testdata_file('JPEG-LL.dcm') # Example: JPEG Lossless\n\nds = pydicom.dcmread(dicom_file_path)\n\n# Accessing .pixel_array will trigger decoding via pylibjpeg-libjpeg\n# if the transfer syntax is supported by the plugin.\npixel_array = ds.pixel_array\n\nprint(f\"DICOM file loaded: {dicom_file_path}\")\nprint(f\"Transfer Syntax UID: {ds.file_meta.TransferSyntaxUID}\")\nprint(f\"Pixel array shape: {pixel_array.shape}\")\nprint(f\"Pixel array dtype: {pixel_array.dtype}\")\nprint(f\"Type of decoded data: {type(pixel_array)}\")","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to a supported Python version (currently >=3.10 and <4.0).","message":"Python 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.","severity":"breaking","affected_versions":">=2.0.0, >=2.4.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`.","message":"NumPy 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.","severity":"breaking","affected_versions":">=2.2.0"},{"fix":"Migrate any code using `utils.reconstruct()` to an alternative approach, likely involving direct pixel array manipulation with NumPy.","message":"The `utils.reconstruct()` function was removed in v2.0.0.","severity":"deprecated","affected_versions":">=2.0.0"},{"fix":"Use other libraries if JPEG encoding functionality is required.","message":"Encoding of JPEG images is not currently supported by `pylibjpeg-libjpeg`; it is a decoding-only library.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review image processing pipelines for potential endianness-related side effects if upgrading on a big-endian system.","message":"Version 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.","severity":"gotcha","affected_versions":">=2.3.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"RuntimeError: Unable to convert the Pixel Data as the 'pylibjpeg-libjpeg' plugin is not installed"},{"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.","cause":"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`.","error":"PyInstaller/cx_Freeze fails to bundle or find 'pylibjpeg-libjpeg' in executable: 'No module named 'pylibjpeg-libjpeg' or GDCM handler error."},{"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.","cause":"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.","error":"AttributeError: partially initialized module 'pydicom' has no attribute 'config' (most likely due to a circular import)"}]}