How to install pydicom¶

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, check this table.

Install using pip¶

pydicom is available on PyPI, the official third-party Python software repository. The simplest way to install from PyPI is using pip with the command:

pip install pydicom

You may need to use this instead, depending on your operating system:

python -m pip install pydicom

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

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

Install using conda¶

pydicom is also available for conda at conda-forge:

conda install -c conda-forge pydicom

Additional type hints¶

The default pydicom type hinting doesn’t cover standard element keywords accessed 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 extra type hints for these attributes you can install the types-pydicom package:

pip install 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)

Downloading example/test DICOM files¶

To keep the package size small, a number of the larger DICOM files are not distributed with pydicom and are instead kept in the pydicom-data repository. To get the complete set of testing and example files you can either install the pydicom-data repository:

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

Or download the missing files to the local cache (after installing pydicom):

python -c "import pydicom; pydicom.data.fetch_data_files()"

Install the optional libraries¶

If you’re going to be manipulating pixel data then NumPy is required.

Using pip:

pip install numpy

Through conda:

conda install numpy

To decode JPEG compressed pixel data one or more additional libraries will need to be installed. See this page for a list of which library is needed to handle a given JPEG format, as specified by the dataset’s (0002,0010) Transfer Syntax UID value.

Installing Pillow¶

Pillow is a popular Python imaging library that can handle the decompression of some JPEG and JPEG 2000 images.

Using pip; you may need to make sure that the libjpeg (for JPEG) and openjpeg (for JPEG 2000) libraries are installed beforehand:

pip install pillow

Through conda:

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

Installing pyjpegls¶

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

Using pip:

pip install pyjpegls

Through conda:

conda install cython
pip install git+https://github.com/pydicom/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:

pip install python-gdcm

The wheels available through conda-forge tend to be older versions and not as well supported. They’re available on conda using:

conda install gdcm -c conda-forge

Installing pylibjpeg¶

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

Using pip:

pip install -U pylibjpeg[all]

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 is 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.