{"id":3753,"library":"pydicom","title":"pydicom","description":"pydicom is a pure Python package for working with DICOM files, the standard for medical imaging and related information. It facilitates reading, modifying, and writing DICOM data into natural pythonic structures. The current version is 3.0.2, and it maintains an active development cycle with several releases per year, including major versions that introduce breaking changes.","status":"active","version":"3.0.2","language":"en","source_language":"en","source_url":"https://github.com/pydicom/pydicom","tags":["DICOM","medical imaging","image processing","data manipulation","healthcare"],"install":[{"cmd":"pip install pydicom","lang":"bash","label":"pip"},{"cmd":"conda install -c conda-forge pydicom","lang":"bash","label":"conda"}],"dependencies":[{"reason":"Recommended for general use; required for manipulating pixel data and accessing `Dataset.pixel_array`.","package":"numpy","optional":true},{"reason":"Optional, for handling certain compressed pixel data (e.g., JPEG, JPEG 2000).","package":"pillow","optional":true},{"reason":"Optional, for handling various compressed pixel data transfer syntaxes.","package":"gdcm","optional":true},{"reason":"Optional, for JPEG-LS compressed pixel data.","package":"jpeg_ls","optional":true},{"reason":"Optional, framework for decompressing various JPEG and RLE images; requires specific plugins.","package":"pylibjpeg","optional":true},{"reason":"Plugin for `pylibjpeg` to support JPEG compression.","package":"pylibjpeg-libjpeg","optional":true},{"reason":"Plugin for `pylibjpeg` to support JPEG 2000 compression.","package":"pylibjpeg-openjpeg","optional":true},{"reason":"Plugin for `pylibjpeg` to support RLE compression.","package":"pylibjpeg-rle","optional":true},{"reason":"Optional, for additional type hints when accessing standard element keywords through `Dataset`.","package":"types-pydicom","optional":true}],"imports":[{"symbol":"pydicom","correct":"import pydicom"},{"note":"Prior to v1.0, the package was imported as `dicom`. Since v3.0, `read_file` and `write_file` have been removed in favor of `dcmread` and `dcmwrite`.","wrong":"import dicom; ds = dicom.read_file(filename)","symbol":"dcmread","correct":"from pydicom import dcmread"},{"symbol":"Dataset","correct":"from pydicom.dataset import Dataset"}],"quickstart":{"code":"import os\nimport pydicom\nfrom pydicom.data import get_testdata_files\n\n# Create a dummy DICOM file for demonstration if it doesn't exist\n# In a real scenario, you would read an existing .dcm file.\ntry:\n    # Using a test file provided by pydicom\n    filename = get_testdata_files(\"CT_small.dcm\")[0]\n    ds = pydicom.dcmread(filename)\n    print(f\"Successfully read: {filename}\")\nexcept Exception as e:\n    print(f\"Could not read test file: {e}. Creating a minimal dataset.\")\n    # Create a dummy dataset if test files are unavailable or for new creation\n    from pydicom.dataset import Dataset, FileDataset, FileMetaDataset\n    from pydicom.uid import generate_uid\n\n    file_meta = FileMetaDataset()\n    file_meta.MediaStorageSOPClassUID = '1.2.840.10008.5.1.4.1.1.2' # CT Image Storage\n    file_meta.MediaStorageSOPInstanceUID = generate_uid()\n    file_meta.ImplementationClassUID = generate_uid()\n\n    ds = FileDataset(\"dummy.dcm\", {}, file_meta=file_meta, preamble=b\"\\0\" * 128)\n    ds.PatientName = \"Doe^John\"\n    ds.PatientID = \"123456\"\n    ds.Modality = \"CT\"\n    ds.StudyInstanceUID = generate_uid()\n    ds.SeriesInstanceUID = generate_uid()\n    ds.SOPInstanceUID = file_meta.MediaStorageSOPInstanceUID\n    ds.SOPClassUID = file_meta.MediaStorageSOPClassUID\n    ds.BodyPartExamined = \"CHEST\"\n    ds.Rows = 128\n    ds.Columns = 128\n    ds.BitsAllocated = 16\n    ds.BitsStored = 12\n    ds.HighBit = 11\n    ds.PixelRepresentation = 0 # unsigned\n    ds.PhotometricInterpretation = \"MONOCHROME2\"\n    ds.SamplesPerPixel = 1\n    ds.PixelData = b'\\x00\\x00' * ds.Rows * ds.Columns # Dummy pixel data\n    ds.is_little_endian = True\n    ds.is_implicit_VR = False\n    ds.save_as(\"dummy.dcm\")\n    filename = \"dummy.dcm\"\n    ds = pydicom.dcmread(filename)\n\n# Accessing DICOM elements\nprint(f\"Patient Name: {ds.PatientName}\")\nprint(f\"Modality: {ds.Modality}\")\n\n# Modifying DICOM elements\nds.PatientName = \"Smith^Jane\"\nprint(f\"New Patient Name: {ds.PatientName}\")\n\n# Adding new elements (if not present in the dictionary, define VR first)\nif 'PhysicianOfRecord' not in ds:\n    ds.add_new('00080090', 'PN', 'Dr. Who') # Tag, VR, Value\nelse:\n    ds.PhysicianOfRecord = 'Dr. New'\nprint(f\"Physician Of Record: {ds.PhysicianOfRecord}\")\n\n# Saving the modified dataset to a new file\noutput_filename = \"modified_image.dcm\"\nds.save_as(output_filename)\nprint(f\"Modified DICOM saved to: {output_filename}\")\n\n# Accessing pixel data (requires numpy)\nif 'PixelData' in ds and 'numpy' in globals():\n    try:\n        pixel_array = ds.pixel_array\n        print(f\"Pixel data shape: {pixel_array.shape}\")\n    except Exception as e:\n        print(f\"Could not access pixel_array: {e}. Is numpy installed?\")\n\n# Clean up (optional)\n# os.remove(output_filename)\n# if filename == \"dummy.dcm\":\n#     os.remove(filename)","lang":"python","description":"This quickstart demonstrates how to read a DICOM file (either a test file or a minimal dummy file), access and modify its metadata elements, and save the changes to a new file. It also shows how to access the pixel data as a NumPy array if available. The example handles the creation of a minimal DICOM file if no test data is readily accessible."},"warnings":[{"fix":"Replace `read_file()` with `dcmread()` and `write_file()` with `dcmwrite()`. Ensure your environment uses Python 3.10 or newer. Be aware of potential changes in pixel data color space conversion.","message":"The functions `read_file()` and `write_file()` have been removed in pydicom v3.0. Users should now use `pydicom.dcmread()` and `pydicom.dcmwrite()` respectively. Additionally, `Dataset.pixel_array` now converts YCbCr Pixel Data to RGB by default. Python versions older than 3.10 are no longer supported.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Update all import statements from `import dicom` to `import pydicom`.","message":"The main package import changed from `import dicom` to `import pydicom` in v1.0. Older code relying on `import dicom` will fail.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Refactor code to use classes and functions from `pydicom.pixels` instead of `pydicom.pixel_data_handlers`.","message":"The `pydicom.pixel_data_handlers` module is deprecated and will be removed in v4.0. Users should migrate to the `pydicom.pixels` module for pixel data handling.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Install necessary optional dependencies for specific compressed transfer syntaxes. Convert to `pixel_array` (requires `numpy`) for image processing. Decompress pixel data before modification if working with compressed images.","message":"Handling compressed pixel data (e.g., JPEG, JPEG 2000) requires additional, optional third-party libraries (`numpy`, `pillow`, `gdcm`, `jpeg_ls`, `pylibjpeg` with its plugins). `PixelData` stores raw bytes, and direct modification of compressed pixel data usually requires decompression first.","severity":"gotcha","affected_versions":"All versions"},{"fix":"When working with private tags, use their full tag number in hexadecimal format or iterate through `ds.elements()` and check `elem.is_private`.","message":"Accessing private DICOM tags by keyword (e.g., `ds.PrivateTag`) is generally not possible. They must be accessed by their tag number (e.g., `ds[0xGGXXEEEE]`) or iterated using `ds.dir()` and inspected.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Enable the future behavior by setting the environment variable `PYDICOM_FUTURE=True` or by calling `from pydicom import config; config.future_behavior(True)` in your code, then test your application thoroughly.","message":"To prepare for future breaking changes, pydicom provides a 'future behavior' flag. Running with this flag can help identify code incompatibilities with upcoming major versions.","severity":"gotcha","affected_versions":"All versions (for future-proofing)"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}