pydicom
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.
Examples are pynetdicom, which is a Python library for DICOM networking, and deid, which supports the anonymization of DICOM files.
Installation
Using pip:
pip install pydicom
Using conda:
conda install -c conda-forge pydicom
For more information, including installation instructions for the development version, see the installation guide.
Documentation
The pydicom user guide, tutorials, examples and API reference documentation is available for both the current release and the development version on GitHub Pages.
Pixel Data
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'
If NumPy is installed, Pixel Data can be converted to an ndarray using the Dataset.pixel_array property:
>>> 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)
Decompressing Pixel Data
JPEG, JPEG-LS and JPEG 2000
Converting JPEG, JPEG-LS or JPEG 2000 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.
RLE
Decompressing 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.
Compressing Pixel Data
Information on compressing Pixel Data using one of the below formats can be found in the corresponding encoding guides. These guides cover the specific requirements for each encoding method and we recommend you be familiar with them when performing image compression.
JPEG-LS, JPEG 2000
Compressing image data from an ndarray or bytes object to JPEG-LS or JPEG 2000 requires installing the following:
- JPEG-LS requires pyjpegls
- JPEG 2000 requires pylibjpeg and the pylibjpeg-openjpeg plugin
RLE
Compressing using RLE requires no additional packages but can be quite slow. It can be sped up by installing pylibjpeg with the pylibjpeg-rle plugin, or gdcm.
Examples
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
With NumPy and matplotlib
import matplotlib.pyplot as plt
from pydicom import dcmread, examples
# The path to the example "ct" dataset included with pydicom
path: "pathlib.Path" = examples.get_path("ct")
ds = dcmread(path)
# `arr` is a numpy.ndarray
arr = ds.pixel_array
plt.imshow(arr, cmap="gray")
plt.show()
Contributing
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.
3 maintainers
Release files for pydicom 3.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pydicom-3.0.2.tar.gz | 2.9 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pydicom-3.0.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 5.3 MB
Release files / pydicom-3.0.2.tar.gz
| Download URL | pydicom-3.0.2.tar.gz |
|---|---|
| Size | 2.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5942bfc2d72c6fa4b3b5b62c527f54b7f2355f21d6f5d296df6bb30188df6a4f
|
|
BLAKE2b-256 checksum How to use checksums |
7ade52aaf905f1f0ae7aba85996e2592ea2c1fe49157f3cfbcd1871965bdb51d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 19, 2026.
Transparency logRelease files / pydicom-3.0.2-py3-none-any.whl
| Download URL | pydicom-3.0.2-py3-none-any.whl |
|---|---|
| Size | 2.4 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
abf971a5440f84dbaf42c4b6758e30e62480902584f8b270b9a5d146e278a07b
|
|
BLAKE2b-256 checksum How to use checksums |
46e060466c6d712dad2cf807df315e39863e91609ffd1064ecb835994460bbda
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Mar 19, 2026.
Transparency log
