Release history

Version 1.3.0



  • New User Guide page for Python 2 support timeline

  • New User Guide page for working with private data elements

  • example loading set of CT slices and plotting axial, sagittal and coronal (#789)


  • Removed deprecated uid variables, config.image_handlers and DeferredDataElement (#760)

  • dataelem.isMultiValue is deprecated and will be removed in v1.4. Use dataelem.DataElement.VM instead.

  • dataelem.isStringOrStringList and dataelem.isString functions are removed

  • datadict.add_dict_entry and datadict.add_dict_entries now raise if trying to add a private tag

  • dataset.Dataset.maxBytesToDisplay also limits display length for non-binary VRs (by number of items) (#666)


  • Added datadict.add_private_dict_entry and datadict.add_private_dict_entries to add custom private tags (#799)

  • Added possibility to write into zip file using gzip, by avoiding seek (#753)

  • Added RLE encoding (#730)

  • Added handling of incorrect transfer syntax (explicit vs implicit) (#820)

  • Added creation of Tag instances by DICOM keyword, e.g Tag(“PatientName”)

  • Added possibility to get and add private tags without adding them to the private dictionary

  • Added possibility to use a Dataset in a NumPy array

  • Allow missing padding byte in Pixel Data, issue a warning in this case (#864)

  • Add in-memory image decoding with GDCM

  • Check really used implicit/explicit VR before reading a data set (#819, #820)

  • Added alpha conversion of Datasets to/from JSON format (Python 3 only)


  • Correctly handle Dataset.pop and Dataset.setdefault for tuple and keyword arguments (#852)

  • Correctly handle encoding errors when any of the encodings are invalid (not just the first) (#850)

  • Do not raise while resolving an ambiguous VR dependent on PixelRepresentation if both PixelRepresentation and PixelData are not present (#838)

  • Raise exception with specific message if value is too large to be written in explicit transfer syntax (#757)

  • Make hash for PersonName3 behave as expected, make PersonName objects immutable (#785)

  • Fixed generate_uid() returning non-conformant UIDs when prefix=None (#788)

  • Avoid exception if reading from empty file (#810)

  • An invalid encoding is now replaced by the default encoding, if config.enforce_valid_values is not set (#815)

  • Correctly handle elements with ambiguous VR in sequence items (#804)

  • Fix bug where new DicomDir objects always have is_implicit_VR

  • Fix dataset equality for mixed raw vs converted data elements (#835)

  • Remove excess padding in Pixel Data

  • Fix wrong date format in anonymize example

  • Fix unknown VR exception message when VR isn’t ASCII (#791)

  • Fix jis-x-0201 characters encoding (#856)

Version 1.2.0



  • PIL removed as a fallback if Pillow is not available in the pillow pixel data handler (#722)

  • uid.JPEGBaseLineLossy8bit deprecated and will be removed in v1.3. Use uid.JPEGBaseline instead. (#726)

  • uid.JPEGBaseLineLossy12bit deprecated and will be removed in v1.3. Use uid.JPEGExtended instead. (#726)

  • uid.JPEG2000Lossy deprecated and will be removed in v1.3. Use uid.JPEG2000 instead. (#726)

  • Equality and inequality operator overrides removed from UID.

  • config.image_handlers deprecated and will be removed in v1.3. - use config.pixel_data_handlers instead. There is also a change in behavior in that image_handlers previously used to only contain the pixel data handlers that had their dependencies met. Now pixel_data_handlers contains all handlers no matter whether or not their dependencies are met. To check if a handler is available for use (it has its dependency met) use the handler’s is_available method.

  • DeferredDataElement class deprecated and will be removed in v1.3 (#291)

  • The use of NumPyPy with PyPy is no longer supported, use NumPy instead.


  • Updated DICOM dictionary for 2018c edition (#677)

  • Added possibility to set byte strings as value for VRs that use only the default character set (#624)

  • Functions for encapsulating frames added to encaps module (#696)

  • Added Dataset.fix_meta_info() (#584)

  • Added new function for bit packing pack_bits for use with BitsAllocated = 1 (#715)

  • Added/corrected encoding and decoding of text and person name VRs using character sets with code extensions, added handling of encoding/decoding errors (#716)

  • Handle common spelling errors in Specific Character Set values (#695, #737)

  • Added uid.JPEGLosslessP14 for UID 1.2.840.10008.

  • Added uid.JPEG2000MultiComponentLossless for UID 1.2.840.10008.

  • Added uid.JPEG2000MultiComponent for UID 1.2.840.10008.

  • Added full support for Planar Configuration (#713)

  • Added support for single frame pixel data where BitsAllocated > 8 and SamplesPerPixel > 1 (#713)

  • Small improvement in RLE decoding speed (~10%)

  • Added support for non-conformant RLE segment ordering (#729)


  • Removed unused original_string attribute from the DataElement class (#660)

  • Improve performance for Python 3 when dealing with compressed multi-frame Pixel Data with pillow and jpeg-ls (#682)

  • Fixed handling of private tags in repeater range (#689)

  • Fixed Pillow pixel data handler for non-JPEG2k transfer syntax (#663)

  • Fixed handling of elements with ambiguous VR (#700, #728)

  • Adapted pixel handlers where endianess is explicitly adapted (#704)

  • Improve performance of bit unpacking (#715)

  • First character set no longer removed (#707)

  • Fixed RLE decoded data having the wrong byte order (#729)

  • Fixed RLE decoded data having the wrong planar configuration (#729)

  • Fixed numpy arrays returned by the pixel data handlers sometimes being read-only. Read-only arrays are still available for uncompressed transfer syntaxes via a keyword argument for the numpy pixel data handler and should help reduce memory consumption if required. (#717)

  • Fixed deprecation warning in Python 3.7 (#740)

Version 1.1.0



  • UID.__str__ no longer returns the UID name (when known). The UID name is still available using the property.

  • Dataset equality now only compares the dataset’s DataElements (#464)

  • the codify script now supports VRs OD and OL, and works in Python 3 (#498); documentation has been added for codify

  • the performance for reading and writing datasets has been improved to be better than in pydicom 0.9.9 (#605, #512)

  • added support for bit-packed pixel data (#292)

  • updated DICOM dictionary for 2018b edition

  • added full API documentation to pydicom documentation (#649)


  • UID should behave as expected for a python str subclass (#256)

  • group length elements in groups above 0x0006 removed on writing (#32)

  • fixed write_PN raising a TypeError when called with a non-iterable encoding parameter (#489)

  • fixed padding for some odd-sized image data (#599)

  • removed unneeded warning for incorrect date string length (#597)

  • fixed Dataset not slicing correctly when an (0xFFFF,0xFFFF) element is present (#92)

  • use correct VR for unknown private tags and private creators (#620)

  • fixed crash on reading RGB data with implicit VR (#620)

  • parent encoding was not used in sequences without own encoding (#625)

  • fixed error handling for values too large to fit in VR IS (#640)


  • A deprecation warning has been added for UID.__eq__ and UID.__ne__ when comparing UID == [UID name] and UID != [UID name]. Starting in v1.2, UID equality and inequality comparisons will return False when performing the equivalent of UID == [UID name] and UID != [UID name], respectively. E.g. UID(‘1.2.840.10008.1.1’) == ‘Verification SOP Class’ will return False. Use == [UID name] instead.

Version 1.0.0

This is a major release, with major changes, including backwards-incompatible changes.


We urge you to review the Transition Guide if you have previously used a pydicom version less than 1.0.


Major changes

  • full Python 3 compatibility - one code base for both Python 2 and Python 3

  • package name and import name now match – use import pydicom rather than import dicom.

  • added Handling of compressed image data:
    • optional GDCM support for reading files with compressed pixel data (#18)

    • optional Pillow and jpeg_ls support for reading some compressed pixel data files

    • support for decompressing a compressed dataset in-place

  • DICOM dictionary updated to 2017c

  • cleaned up DICOM dictionary code, old non-DICOM-keyword code removed

Other enhancements

  • added util/ callbacks available to fix non DICOM-compliant values before exceptions thrown

  • added context management methods to Dataset

  • added misc.is_dicom() function to check for DICOM file format

  • added date/time converters (#143)

  • added option to attempt other VRs if translate fails (#197)

  • added heuristics to read files that have no preamble or file meta information

  • support for multi-valued DA, DT, TM data elements (#212)

  • DataElement: added keyword and is_retired properties

  • datadict: added dictionary_is_retired()

  • datadict: added ability to add custom DICOM dictionary items via add_dict_entry() and add_dict_entries()

  • added some support for pickle

  • added support for VRs OD, OL and UC

  • added support for Thai, Japanese and Chinese encodings (#346, #353)

  • added support for slicing to Dataset

  • add/update TransferSyntaxUID when writing standard

  • renamed UID package to uid (conforms to Python standard)

  • added property uid.is_private

  • added definitions for storage SOP Class UIDs (#172)

  • added possibility to read only specific tags (#95)

  • added missing meta elements when writing DICOM file

  • added encaps generator functions to access compressed frames

  • read_file changed to dcmread, write_file to dcmwrite for greater clarity. Previous names still available for backwards compatibility.



  • correctly handle PlanarConfiguration==0 (#151)

  • updated uid generation to ensure uniqueness (#125)

  • handle missing patient data in show_dicomdir

  • assume default transfer syntax if none in file meta (#258)

  • fixed reading/writing of empty tags and tags with bad VR

  • fixed reading AE elements with leading or trailing spaces

  • fixed handling of ambiguous VR elements

  • fixed handling for several error conditions

  • fixed Latin5 (Turkish) character set handling

  • a lot of other small fixes…

Version 0.9.9


In addition to bug fixes, pydicom 0.9.9 contains updates for all DICOM dictionaries. New features include DICOMDIR handling, and a utility module which produces python/pydicom source code to recreate a DICOM file.


  • All DICOM dictionaries updated (standard dictionary, UID dictionary, and private dictionaries)

  • Dicom commands also added to dictionary

  • Ability to work with DICOMDIR: read_dicomdir() function and DicomDir class. Example file file added to examples subdirectory.

  • Produce python/pydicom source code from a DICOM file.

  • a number of Python 3 compatibility enhancements

  • uses ez_setup only if setuptools not already installed

  • exceptions carry tag info with them, to aid in debugging

Contrib file changes

  • pydicom_series: force parameter added (Nil Goyette)

  • dcm_qt_tree: switch to OrderedDict to preserve ordering of tags (Padraig Looney)

Other Contributors

Other than Jonathan and myself, other contributors were: Rickard Holmberg, Julien Lamy, Yaroslav Halchenko, Mark White, Matthew Brett, Dimitri Papadopoulos, videan42 …(sorry if I’ve missed anyone).

Version 0.9.8


pydicom 0.9.8 is mainly a consolidation step before moving to official Python 3 compatibility in pydicom 1.0. It also reverts the change to using Decimal for VR of DS (in pydicom 0.9.7), due to performance issues. DS as Decimal is still available, but is off by default.

Major changes

  • Requires Python 2.6 or later, in preparation for Python 3 compatibility

  • experimental Python 3 compatibility (unofficial at this point) – uncomment the two indicated lines in to use it. Please provide feedback to the issues list.

  • DS values reverted to using float as default (issue 114) due to slow performance using Python Decimal. Speed tests show approx factor of 10 improvement compared with pydicom 0.9.7 (several revisions up to r78ba350a3eb8)

  • streamlined much code internally taking advantage of modern Python constructs: decorators, generators, etc

Bug fixes

  • Fix for duplicate logger from Gunnar Schaefer. Fixes issue 107 (revision 774b7a55db33)

  • Fix rewind behavior in find_bytes (issue 60, revision 6b949a5b925b)

  • Fix error in nested private sequences (issue 113, revision 84af4b240add)


  • UID generator added (Félix C. Morency) (revisions 0197b5846bb5 and 3678b1be6aca, tests in f1ae573d9de5, 0411bab7c985)

  • new PersonName3 class for Python 3: (revision 9b92b336e7d4)

Contrib file changes

  • Fix for pydicom_series for DS decimal (revision e830f30b6781)

  • new module - tree display of DICOM files using PySide and Qt. Contributed by Padraig Looney.

Special acknowledgement to Jonathan Suever who contributed most of the Python 3 work and many bug fixes.

Version 0.9.7


pydicom 0.9.7 resolves some remaining bugs before moving to Python 3 compatibility. ** It is the last version which will run with Python < 2.6 ** (it will run with Python 2.4 to Python 2.7)

Major changes

  • Added DICOM 2011 keywords. Old “named tags” still work, but will be

deprecated in future versions. Most names are identical, but some have changed. For example: * SamplesperPixel becomes SamplesPerPixel (capital ‘P’ on ‘Per’) * Beams becomes BeamSequence (and similar for all sequences) * Decimal and integer strings handled much better (revisions 4ed698a7bfbe and


  • New classes for VR of types DS and IS (DS is derived from Python Decimal)

  • New MultiValue class, enforcing all values of same type

  • New file with user-definable parameters:

  • allow_DS_float (default False) for controlling whether float values can be used to construct DS or IS strings.

  • enforce_valid_values (default True) for ensuring IS, DS meet DICOM standard limits To change these, use ‘import dicom.config, then dicom.config.<parameter>={True|False}’ before setting values of data elements

Users are encouraged to switch to the official DICOM keywords, as these are now part of the standard, and promote consistency across programming languages and libraries.

Bug fixes

  • New way to read file meta information, not using the group length, instead reading until end of group 2 data elements. If group length dose not match, log a warning (revision b6b3658f3b14).

  • Fix bug in copying raw private data elements (issue 98)

  • Force logging level to warning on ‘import dicom’ (issue 102)

  • Deferred read fixed to work with gzipped files (issue 103)

  • Setting individual items in a DS or IS list now saves to file correctly

  • Japanese and Korean encoding fixes (issue 110)

Other Enhancements

  • New Sequence class which verifies items are Datasets (issue 52)

  • Assignment to SQ data element checks value is a Sequence or can be converted to one (issue 111)

  • dir(ds) now includes methods and properties as well as DICOM named tags. Work only on Python >= 2.6 as previous versions do not call __dir__ method (issue 95)

  • Added much more debugging info and simplified reading of data elements (revision b6b3658f3b14)

  • updated example files to DICOM 2011 keywords; fixed bugs

Many of the bug fixes/enhancements were submitted by users. Many thanks to those who contributed.

Version 0.9.6


pydicom 0.9.6 updates the dictionary to the DICOM 2011 standard, and has a number of bug fixes

Major changes

  • updated the dictionary to the DICOM 2011 standard’s dictionary.

Bug fixes

  • Fixed bug in Dataset.file_metadata() and deprecated in favor of FileDataset (issue 93)

  • Fixed UID comparisons against non-string values (issue 96)

  • catch exceptions on reading undefined length private data elements (issue 91, issue 97)

  • Fixed bug in raising exception for unknown tag


  • added example file to show how to create DICOM files from scratch

  • updated other example files

  • more PEP-8 style changes

Version 0.9.5


pydicom 0.9.5 is primarily a bug-fix release but includes some contrib files also.

Major fixes in this release

  • fix for incorrect pixel integer types which could lead to numeric errors (issue 79)

  • By default an InvalidDicomError will be raised when trying to read a non-DICOM file (unless read_file keyword arg {{{force}}} is True) (revision fc790f01f5)

  • fix recursion error on private data elements (issue 81, issue 84)

Other fixes in this release

  • Fix for unicode decode failing with VM > 1 (issue 78)

  • fix for fail of DicomIter on files with Explicit VR Transfer Syntax UID (issue 82)

  • Fix for Python 2.5 and ‘with’ statement (revision 1c32791bf0)

  • Handle ‘OB/OW’ VR as well as ‘OW/OB’ (revision e3ee934bbc)

  • Fix dataset.get(tag) so returns same as dataset[tag] (issue 88)

New ‘Contrib’ files

  • by Mike Wallace – CouchDB storage of DICOM info and binary data

  • by Almar Klein – Reads files and separates into distinct series.


  • switch to Distribute for packaging

  • preliminary work on Python 3 compatiblity

  • preliminary work on using sphinx for documentation

  • preliminary work on better writing of files from scratch

Version 0.9.3


Major changes

  • changed to MIT-style license

  • option to defer reading of large data element values using read_file()’s new defer_size argument (r102, r103)

  • dictionary of private tags added – descriptive text shown when available (issue36, r97, r110)

  • more conversion to PEP-8 style. Should now use read_file(), save_as(), pixel_array rather than !ReadFile(), !SaveAs(), !PixelArray. Old names kept for now as aliases.

Other Enhancements

  • added DicomFileLike class to simplify and generalize access. Any object that has read, write, seek, tell, and close can now be used. (r105)

  • added dataset.iterall() function to iterate through all items (including inside sequences) (r105)

  • added dataset.formatted_lines() generator to allow custom formatting (r91, r113)

  • made reading tolerant of truncated files – gives a warning, but returns dataset read to that point (r95)

Bug Fixes

  • fixed issue38, name collision for ‘Other Patient Ids’ as both data element and sequence name in DICOM standard (r95, r96)

  • fixed issue40, blank VRs in some DICOM dictionary entries caused NotImplementError on reading (r100)

  • fixed issue41, reading VRs of ‘US or SS’ and similar split on backslash character (r104)

  • fixed bug where TransferSyntaxUID not present when reading file without DICOM header (r109)

  • fixed print recursion bug when printing a UID (r111)


  • many of the example files updated

  • updated anonymize example file to also deal with ‘OtherPatientIDs’ and ‘PatientsBirthDate’ (r98)

Version 0.9.2


Major changes

  • Renamed Attribute class and related modules to !DataElement. Old code will continue to work until pydicom 1.0, but with a !DeprecationWarning (issue22, r72, r73)

  • Added support for character sets through Specific Character Set (0008,0005), using Python unicode. Thus foreign languages can display names in Greek, Japanese, Chinese etc characters in environments which support unicode (demonstrated in example using Tkinter GUI) (r64, r65)

Other Enhancements

  • Added support for auto-completion of dataset elements in ipython; also all environments using Python 2.6 (r69, r70)

  • Added __iter__() to Dataset so returns data elements in DICOM order with “for data_elem in dataset:” (r68)

  • Added example program showing a DICOM file in a GUI window (Tkinter/Tix).

  • Added !PersonName class to parse components of names more easily (r55)

  • Added UID class to handle UID values. Name rather than UID number shown, UID_dictionary used (r51).

  • Code tested under Python 2.6

  • Added ! property; synonym for !DataElement.description() function

Bug Fixes

  • Fixed issue27, sequence with a single empty item read incorrectly

  • Fixed bug that read_OW did not handle !UndefinedLength (r50)

  • Fixed bugs in example files, !, and (r51)

  • Fixed issue33, VR=UN being split on backslash (r70)

  • Fixed issue18, util directory not installed (r45)


  • Added example file – shows how to custom format DICOM file information (r67)

  • Reorganized test files and added various new tests

  • added preliminary work on encapsulated data (r50)

  • added some simple files to view or work with pixel data (r46)

  • Dataset.!PixelDataArray() NumPy array changed to property Dataset.!PixelArray

  • changed to setuptools for packaging rather than distutils