pydicom is a pure Python package for working with DICOM files. It lets you read, modify and write DICOM data in an easy "pythonic" way. As a pure Python package, pydicom can run anywhere Python runs without any other requirements, although if you're working with Pixel Data then we recommend you also install NumPy.
Note that pydicom is a general-purpose DICOM framework concerned with reading and writing DICOM datasets. In order to keep the project manageable, it does not handle the specifics of individual SOP classes or other aspects of DICOM. Other libraries both inside and outside the pydicom organization are based on pydicom and provide support for other aspects of DICOM, and for more specific applications.
pip install pydicom
conda install -c conda-forge pydicom
For more information, including installation instructions for the development version, see the installation guide.
Compressed and uncompressed Pixel Data is always available to be read, changed and written as bytes:
>>> from pydicom import dcmread >>> from pydicom.data import get_testdata_file >>> path = get_testdata_file("CT_small.dcm") >>> ds = dcmread(path) >>> type(ds.PixelData) <class 'bytes'> >>> len(ds.PixelData) 32768 >>> ds.PixelData[:2] b'\xaf\x00'
>>> arr = ds.pixel_array >>> arr.shape (128, 128) >>> arr array([[175, 180, 166, ..., 203, 207, 216], [186, 183, 157, ..., 181, 190, 239], [184, 180, 171, ..., 152, 164, 235], ..., [906, 910, 923, ..., 922, 929, 927], [914, 954, 938, ..., 942, 925, 905], [959, 955, 916, ..., 911, 904, 909]], dtype=int16)
Compressed Pixel Data
JPEG, JPEG-LS and JPEG 2000
Converting JPEG compressed Pixel Data to an
ndarray requires installing one or more additional Python libraries. For information on which libraries are required, see the pixel data handler documentation.
Compressing data into one of the JPEG formats is not currently supported.
Encoding and decoding RLE Pixel Data only requires NumPy, however it can be quite slow. You may want to consider installing one or more additional Python libraries to speed up the process.
More examples are available in the documentation.
Change a patient's ID
from pydicom import dcmread ds = dcmread("/path/to/file.dcm") # Edit the (0010,0020) 'Patient ID' element ds.PatientID = "12345678" ds.save_as("/path/to/file_updated.dcm")
Display the Pixel Data
import matplotlib.pyplot as plt from pydicom import dcmread from pydicom.data import get_testdata_file # The path to a pydicom test dataset path = get_testdata_file("CT_small.dcm") ds = dcmread(path) # `arr` is a numpy.ndarray arr = ds.pixel_array plt.imshow(arr, cmap="gray") plt.show()
We are all volunteers working on pydicom in our free time. As our resources are limited, we very much value your contributions, be it bug fixes, new core features, or documentation improvements. For more information, please read our contribution guide.
If you have examples or extensions of pydicom that don't belong with the core software, but that you deem useful to others, you can add them to our contribution repository: contrib-pydicom.