Installation#

Note

We recommend installing into a virtual environment, which is an isolated Python environment that allows you to install packages without admin privileges.

Install the official release#

pydicom, being a Python library, requires Python. If you’re not sure whether or not your version of Python is supported, you can check this table.

pip install -U pydicom

conda install -c conda-forge pydicom

You can also perform an offline installation by downloading and installing one of the release *.whl files. For example, with the file for the v3.0 release:

pip install pydicom-3.0.1-py3-none-any.whl

Additional type hints#

pydicom’s default type hinting doesn’t cover standard elements accessed via their keyword through Dataset:

# foo.py
from pydicom import Dataset

ds = Dataset()
ds.PatientName = 1234

$ mypy foo.py
Success: no issues found in 1 source file

To add type hints for these attributes you can install the types-pydicom package:

pip install -U types-pydicom

$ mypy foo.py
foo.py:5: error: Incompatible types in assignment (expression has type "int", variable has type "str | PersonName | None")  [assignment]
Found 1 error in 1 file (checked 1 source file)

Install the optional libraries#

Converting raw pixel data to an ndarray always requires NumPy, and decoding JPEG compressed pixel data requires installing one or more additional libraries.

The quickest way to install NumPy and all the additional libraries is with:

pip install -U pydicom[pixeldata]

conda install -c conda-forge pydicom[pixeldata]

Alternatively, you can install only the libraries you need. NumPy is always required, and can handle converting uncompressed pixel data to an ndarray without any other packages:

pip install -U numpy

conda install numpy

For compressed pixel data, see this page for details of which library is needed to compress or decompress using a given compression method, as specified by the dataset’s (0002,0010) Transfer Syntax UID value, then follow the corresponding installation instructions below.

Installing Pillow#

Pillow is a popular Python imaging library that can handle the decompression of some JPEG and JPEG 2000 images. It includes JPEG support by default, however JPEG 2000 requires the openjpeg library be installed.

pip install -U pillow

conda install -c conda-forge openjpeg jpeg
conda install pillow

Installing pylibjpeg#

pylibjpeg is a Python framework for decompressing JPEG, JPEG-LS images and compressing or decompressing JPEG 2000 and RLE images, provided a suitable plugin is installed.

pip install -U pylibjpeg[all]

conda install -c conda-forge pylibjpeg[all]

Installing pyjpegls#

pyjpegls is a Python interface to the CharLS C++ library and can compress and decompress JPEG-LS images. It’s a fork of CharPyLS created to provide compatibility with the latest Python versions.

pip install -U pyjpegls

conda install -c conda-forge pyjpegls

Installing GDCM#

GDCM is a C++ library for working with DICOM datasets that can decompress JPEG, JPEG-LS and JPEG 2000 images.

The wheels on PyPI are built by the python-gdcm project for current versions of Python on Windows, MacOS and Linux, and can be installed using pip.

The wheels available through conda-forge tend to be older versions and may not be as well supported.

pip install -U python-gdcm

conda install -c conda-forge gdcm

Install the development version#

To install a snapshot of the latest code (the main branch) from GitHub:

pip install git+https://github.com/pydicom/pydicom

The main branch is under active development and while it’s usually stable, it may have undocumented changes or bugs.

If you want to keep up-to-date with the latest code, make sure you have Git installed and then clone the main branch (this will create a pydicom directory in your current directory):

git clone --depth=1 https://github.com/pydicom/pydicom.git

Then install using pip in editable (-e) mode:

pip install -e pydicom/

When you want to update your copy of the source code, run git pull from within the pydicom directory and Git will download and apply any changes.