dcmodify(1)

📦

version 3.7.1 · 10 versions

💅 dcmodify — the OFFIS DCMTK era, bestie

okay so welcome to dcmodify(1) from the DCMTK corner of the universe 🎀 this is the manual page, but make it make sense, yk? Let's go.

✨ NAME

dcmodify — Modify DICOM files. that's the whole vibe. she modifies. she's a modifier. 💅

🦋 SYNOPSIS

dcmodify [options] dcmfile-in...

🌸 DESCRIPTION

okay so dcmodify is that girl — she lets you modify, insert, and delete tags and items in DICOM files. Sequences? supported. Tags with a value multiplicity > 1? also supported, no cap. 🫶

but bestie, listen: metaheader information and the tag's VR can not be modified directly by dcmodify at this time. she said "not today" to those. 😭

on top of tag modifications, dcmodify also hands you some input options — which force dcmodify to handle its input files exactly the way you specify — plus output options that control the output format of the resulting files. she's very accommodating like that. ✨

in case you need multiple modifications done? dcmodify does them in the same order as they appear on the command line. order matters, bestie, she is NOT shuffling your queue. 🔥

and heads up: dcmodify does not check whether a given value matches its value representation (VR). usually an error message gets printed, but generally the user — that's you, babe — should take care of the right VR usage. she trusts you. 🙈

if dcmodify doesn't know the tag it should insert, then the tag's VR is set to UN and the value you provided on the command line is interpreted as being a series of hexadecimal numbers (like they are provided for VR=OB). iconic but chaotic 💀 — please insert these tags into the dictionary to avoid this behavior.

also, by specifying the -iun option, it's possible to force dcmodify to leave UN values untouched. and using option -u lets dcmodify save all VR=UN attributes as OB. slay, options.

🧚 tag paths, aka how to reach into the void

dcmodify is able to work with so-called tag paths to access tags in sequences. the (pseudo-formalized) syntax is:

{sequence[item-no].}*element

where:

'sequence' is a sequence tag like (0008,1111) or a dictionary name for a tag.
'item-no' describes the item number to be accessed (counting from zero).
'element' defines the target tag to work on.

a tag can either be specified directly as (0010,0010) or through the corresponding dictionary name "PatientName". the '*' denotes that you can repeat sequence statements to access deeper levels in DICOM files (see EXAMPLES section — coming at you in a later part 👀). for 'item-no', also a wildcard character '*' can be used, selecting all items in surrounding sequence (see section WILDCARDS below, also later 💖).

when inserting tag paths consisting of multiple nodes (i.e. not a single element) using the -i option, any missing path elements (items, sequences, leaf elements) are inserted automatically when missing. she fills in the blanks, main character energy 👑

that does not work for item wildcards: when no single item exists in the surrounding sequence, dcmodify of course can't decide how many items should be generated. she's good, not psychic. 😭

however, if you specify an item number like '5', all 6 items (counted from zero) can be (and are) automatically generated in insert mode. and if 2 items already exist, the rest (4) would be inserted. math is math, and she ate. 🔥

🌈 conditions, because sometimes you're picky

dcmodify can be instructed to execute the specified element modifications only under certain conditions, which you provide by specifying one or more -iff (--process-if) options. each condition specifies a path to an element and a comparison operator plus value if needed.

available conditions are:

checking for the existence of an element tag (e.g. 'PatientName' and '!PatientName')
comparisons against the value of an element, as in 'Rows<513', 'Rows<=512', '(0028,0010)>512' and '(0028,0010)>=513' (-iff omitted for brevity)

the tag syntax follows the same rules as for other dcmodify options (tag path). consistent queen 💅

one extension is that for elements with multiple values, i.e. with a Value Multiplicity (VM) greater than 1, the tag of the target (leaf) element can be followed by an index in square brackets, similar to the item index syntax used for sequences, e.g. ImageType[2], in order to address the 3rd value of the ImageType element. cute and functional 🎀

all conditions specified with the --process-if option are combined using a logical "AND", i.e. if at least one condition is not true, dcmodify will not perform any modifications on the specified DICOM file(s). it's giving "all or nothing" and honestly? respect. 💜

⭐ small but important warnings

dcmodify does not work on directories, i.e. the parameter dcmfile-in... must not include directory names. no folders, bestie, she said files only 🙅‍♀️

please note that there are some issues concerning the modification of private tags (see the PRIVATE TAGS section) and for changing UIDs (the CHANGING UIDs section). more on those later in this page — stay tuned 🦋

👑 PARAMETERS

dcmfile-in — DICOM input filename(s) to be modified ("-" for stdin/stdout). yes, a dash, she'll read from stdin and write to stdout, versatile icon ✨

💅 OPTIONS

🫶 general options

-h, --help — print this help text and exit
--version — print version information and exit
--arguments — print expanded command line arguments
-q, --quiet — quiet mode, print no warnings and errors (she's shushing 🤫)
-v, --verbose — verbose mode, print processing details (she's oversharing 💖)
-d, --debug — debug mode, print debug information
-ll, --log-level [l]evel: string constant — (fatal, error, warn, info, debug, trace) use level l for the logger
-lc, --log-config [f]ilename: string — use config file f for the logger

🌸 input options

🎀 input file format

+f, --read-file — read file format or data set (default)
+fo, --read-file-only — read file format only
-f, --read-dataset — read data set without file meta information
+fc, --create-file — create file format if file does not exist

🦋 input transfer syntax

-t=, --read-xfer-auto — use TS recognition (default)
-td, --read-xfer-detect — ignore TS specified in the file meta header
-te, --read-xfer-little — read with explicit VR little endian TS
-tb, --read-xfer-big — read with explicit VR big endian TS
-ti, --read-xfer-implicit — read with implicit VR little endian TS

🧚 parsing of odd-length attributes

+ao, --accept-odd-length — accept odd length attributes (default)
+ae, --assume-even-length — assume real length is one byte larger

🌈 automatic data correction

+dc, --enable-correction — enable automatic data correction (default)
-dc, --disable-correction — disable automatic data correction

⭐ bitstream format of deflated input

+bd, --bitstream-deflated — expect deflated bitstream (default)
+bz, --bitstream-zlib — expect deflated zlib bitstream

🔥 processing options

💜 backup input files

--backup — backup files before modifying (default)
-nb, --no-backup — don't backup files (DANGEROUS 💀 — like, actually, she warned you)

🎀 conditional execution

-iff, --process-if "[c]ondition" — only perform modification(s) if condition c holds true

✨ insert mode

-i, --insert "[t]ag-path=[v]alue" — insert (or overwrite) path at position t with value v
-if, --insert-from-file "[t]ag-path=[f]ilename" — insert (or overwrite) path at position t with value from file f
-nrc, --no-reserv-check — do not check private reservations

🦋 modify mode

-m, --modify "[t]ag-path=[v]alue" — modify tag at position t to value v
-mf, --modify-from-file "[t]ag-path=[f]ilename" — modify tag at position t to value from file f
-ma, --modify-all "[t]ag=[v]alue" — modify ALL matching tags t in file to value v

🌸 erase mode

-e, --erase "[t]ag-path" — erase tag/item at position t
-ea, --erase-all "[t]ag" — erase ALL matching tags t in file
-ep, --erase-private — erase ALL private data from file. she said privacy? gone. periodt. 🙈

👑 unique identifier

-gst, --gen-stud-uid — generate new Study Instance UID
-gse, --gen-ser-uid — generate new Series Instance UID
-gin, --gen-inst-uid — generate new SOP Instance UID
-nmu, --no-meta-uid — do not update metaheader UIDs if related UIDs in the dataset are modified

🎀 error handling

-ie, --ignore-errors — continue with file, if modify error occurs
-imt, --ignore-missing-tags — treat 'tag not found' as success when modifying or erasing in files
-iun, --ignore-un-values — do not try writing any values to elements having a VR of UN

💖 output options

🌟 output file format

+F, --write-file — write file format (default)
-F, --write-dataset — write data set without file meta information

🦋 output transfer syntax

+t=, --write-xfer-same — write with same TS as input (default)
+te, --write-xfer-little — write with explicit VR little endian TS
+tb, --write-xfer-big — write with explicit VR big endian TS
+ti, --write-xfer-implicit — write with implicit VR little endian TS

🎀 post-1993 value representations

+u, --enable-new-vr — enable support for new VRs (UN/UT) (default)
-u, --disable-new-vr — disable support for new VRs, convert to OB

✨ group length encoding

+g=, --group-length-recalc — recalculate group lengths if present (default)
+g, --group-length-create — always write with group length elements
-g, --group-length-remove — always write without group length elements

🌈 length encoding in sequences and items

+le, --length-explicit — write with explicit lengths (default)
-le, --length-undefined — write with undefined lengths

💜 data set trailing padding (not with `--write-dataset`)

-p=, --padding-retain — do not change padding (default if not --write-dataset)
-p, --padding-off — no padding (implicit if --write-dataset)
+p, --padding-create [f]ile-pad [i]tem-pad: integer — align file on multiple of f bytes and items on multiple of i bytes

okay that's the first chunk, bestie — more of the page is coming at you next, so don't go anywhere 💅✨

💅 PRIVATE TAGS 💅

Okay bestie, private tags have some ✨situations✨ you have to consider. However, the insertion or modification of a reservation tag (gggg,00xx) should always work. 🫶

✨ Insertions ✨

If you wish to insert a private tag (not a reservation with gggg,00xx), be sure that you've listed it in your dictionary (see <docdir>/datadict.txt for details). If it's not listed, dcmodify will insert it with VR=UN. Also, for some cases insertion may even fail for some values. 😭

If you've got your private tag in the dictionary, dcmodify acts as follows: when it finds a reservation in the tag's enclosing dataset, whose private creator matches, insertion is done with the VR found in the dictionary and the value given on command line. But if the private creator doesn't match or none is set, dcmodify will return with an error. If a private tag should be inserted regardless whether a reservation does not exist, the option -nrc can be used, forcing an insertion. However, the VR is set to UN then, because the tag then cannot be found in the dictionary. 💀

See description above how inserting values into elements with unknown VR are handled. 👑

🎀 Modifications 🎀

If you modify a private tag's value, dcmodify won't check its VR against the dictionary.

So please be careful to enter only values that match the tag's VR. 🙈

If you wish to change a private tag's value and VR, because you just added this tag to your dictionary, you can delete it with dcmodify and re-insert it. Then dcmodify uses your dictionary entry to determine the right VR (also see subsection insertions). 💅

Also, see description above how inserting values into elements with unknown VR are handled. ✨

🦋 Deletions 🦋

When you use dcmodify to delete a private reservation tag, please note that dcmodify won't touch the private tags that are under this reservation. The user is forced to handle the consistency between reservations and their associated private tags. 🫠

For the deletion of private non-reservation tags there are no special issues. 🌸

🌈 CHANGING UIDS 🌈

dcmodify will automatically correct 'Media Storage SOP Class UID' and 'Media Storage SOP Instance UID' in the metaheader, if you make changes to the related tags in the dataset ('SOP Class UID' and 'SOP Instance UID') via insert or modify mode options. You can disable this behavior by using the -nmu option. 💅

If you generate new UID's with -gst, -gse or -gin, this will only affect the UID you chose to generate. So if you use -gst to generate a new 'Study Instance UID', then 'Series Instance UID' and 'SOP Instance UID' will not be affected! This gives you the possibility to generate each value separately. Normally, you would also modify the 'underlying' UIDs. As a disadvantage of this flexibility, the user has to assure, that when creating 'new' DICOM files with new UIDs with dcmodify, other UIDs have to be updated by the user as necessary. 🔥

When choosing the -gin option, the related metaheader tag ('Media Storage SOP Instance UID') is updated automatically. This behavior cannot be disabled. ⭐

When working on multiple input files, dcmodify processes each file in isolated fashion, i.e. it will generate UIDs for each single file. For example, when using the -gst option, dcmodify will insert a different Study Instance UID into each file instead of generating a single one and writing it to each file that is being processed. 🎀

🌸 CREATING NEW FILES 🌸

Option --create-file lets dcmodify create a file if it does not already exist on disk. This can be used in order to create files from scratch by performing consecutive insertions with options like --insert. This might especially become handy when creating query files for tools like findscu or movescu. In case no specific output transfer syntax is defined, dcmodify chooses Little Endian Explicit Uncompressed for output. Files that are newly created are always written as DICOM file format, i.e. option --write-dataset is not permitted together with --create. This way, at least the metaheader is written and no file with zero byte length is created in a case where no insertions are performed in the dcmodify call. 🦋

🍓 ELEMENT VALUES FROM FILE 🍓

In order to read the element value from a file instead of specifying it on the command line, option -mf and -if can be used. Please note that for OW elements, the data is expected to be little endian ordered and will be swapped if necessary. The file size should always be an even number of bytes, i.e. no automatic padding is performed. 💜

🧚 WILDCARDS 🧚

dcmodify also permits the usage of a wildcard character "*" for item numbers in path expressions, e.g. "ContentSequence[*].CodeValue" selects all "CodeValue" elements in all items of the ContentSequence. Using a wildcard is possible for all basic operations, i.e. modifying -m, inserting -i and -e options which makes it, together with the automatic creation of intermediate path nodes a powerful tool for construction and processing complex datasets. 👑

The options -ma and -ea for modifying or deleting all occurrences of a DICOM element based on its tag do not accept any wildcards but only work on single elements (i.e. a single dictionary name or tag key). 💅

🔥 PROCESSING CONDITIONS 🔥

Simple conditions can be provided with the option --process-if. All conditions specified with the --process-if option are combined using the logical "AND". ✨

Available condition syntax and its meaning are as listed below:

Existence conditions: checks whether tag exists in DICOM file
- [t]ag: true if tag t exists
- ![t]ag: true if tag t does not exist
Comparison conditions: checks value of given tag
- [t]ag=[v]alue: true if v equals the given value
- [t]ag!=[v]alue: true if v does not equal the given value
- [t]ag<[v]alue: true if v is lesser than the given value
- [t]ag<=[v]alue: true if v is lesser or equals the given value
- [t]ag>[v]alue: true if v is greater the given value
- [t]ag>=[v]alue: true if v is greater or equals the given value

All tags are specified in the same way as for the other options, i.e. using the tag path syntax (including potential use of "*" for item indices). 🫶

Tags not ending in a leaf (items, sequences) are possible for existence checks, but not for comparison checks. The comparison checks fail if the specified tag does not exist at the specified tag path in the file. Dedicated element values of elements with VM > 1 can be accessed as element[index] in condition checks. If an element has VM > 1 but no index is specified, the full content (all values) of the element are handled as single string with values separated by backslash (\). 😭

Comparisons on element values that use string-based VRs are only recommended for equality checks, since using them for conditions <, <=, > and >= must be considered well. As a basis for the comparison, the compare() method defined on the related VR class is used; it uses memcmp() to compare the strings value by value (maximally the VM of the one with less values) and returns on the first difference. If both strings are equal up to the length (VM) of the shorter one, the one with less values is considered less than other one. For example:

- - -

Note that currently also DS and IS values are compared as strings, i.e. '10' is considered less than '2' for DS and IS. 💀

For UID fields like SOPClassUID well-known UID names as specified in the standard (and DCMTK) can be used, e.g. SOPClassUID=CTImageStorage . 🌟

✨ EXAMPLES ✨

Okay bestie, this is the part where the manpage shows off 💅 — every example is here, and every flag matters.

💖 `-i`, `--insert`

dcmodify -i "(0010,0010)=A Name" file.dcm

Inserts the PatientName tag into 'file.dcm' at 1st level. If the tag already exists, -i will overwrite it! 🫣 If you want to insert an element with value multiplicity > 1 (e.g. 4), you can do this with:

dcmodify -i "(0018,1310)=1\\2\\3\\4"

dcmodify -i "(0008,1111)[0].PatientName=Another Name" *.dcm

Inserts the PatientName tag into the first item of sequence (0008,1111). Note that the use of wildcards for files is possible. You can specify longer tag paths, too (e.g. "(0008,1111)[0].(0008,1111)[1].(0010,0010)=A Third One"). If any part of the path, e.g. the sequence or the item "0", does not exist, it is automatically inserted by dcmodify.

dcmodify -i "(0008,1111)[*].PatientName=Another Name" *.dcm

Inserts the PatientName tag into every item of sequence (0008,1111). Note that the use of wildcards for files is possible. You can specify longer tag paths, too (e.g. "(0008,1111)[*].(0008,1111)[*].(0010,0010)=A Third One").

🧚 `-if`, `--insert-from-file`

dcmodify -if "PixelData=pixel.raw" file.dcm

Inserts the content of file 'pixel.raw' into the PixelData element of 'file.dcm'. The contents of the file will be read as is. OW data is expected to be little endian ordered and will be swapped if necessary. No checks will be made to ensure that the amount of data is reasonable in terms of other attributes such as Rows or Columns. 💀 So yeah, behave.

🌸 `-m`, `--modify`

dcmodify -m "(0010,0010)=A Name" file.dcm

Changes tag (0010,0010) on 1st level to "A Name".

This option also permits longer tag paths as demonstrated above for -i. If the leaf element or any intermediate part of the path does not exist, it is not inserted as it would be if using the '-i' option.

dcmodify -m "(0010,0010)=A Name" -imt file.dcm

Changes tag (0010,0010) on 1st level to "A Name". Due to the given option '-imt', success is returned instead of "tag not found", if the element/item (or any intermediate node in a longer path) does not exist.

Note that for the '-m' option the last node in the path must be a leaf element, i.e. not a sequence or an item.

🎀 `-mf`, `--modify-from-file`

dcmodify -mf "PixelData=pixel.raw" file.dcm

Does the same as -if in case there was already a PixelData element in 'file.dcm'. Otherwise nothing is changed.

👑 `-ma`, `--modify-all`

dcmodify -ma "(0010,0010)=New Name" file.dcm

Does the same as -m but works on all matching tags found in 'file.dcm'. Therefore, it searches the whole dataset including sequences for tag (0010,0010) and changes them to "New Name".

🦋 `-e`, `--erase`

dcmodify -e "(0010,0010)" *.dcm

Erases tag (0010,0010) in all *.dcm files at 1st level.

This option also allows longer tag paths as demonstrated above for -i.

dcmodify -e "(0010,0010)" -imt *.dcm

Erases tag (0010,0010) in all *.dcm files at 1st level. Due to the given option '-imt', success is returned instead of "tag not found", if the element/item (or any intermediate node in a longer path) does not exist.

🌈 `-ea`, `--erase-all`

dcmodify -ea "(0010,0010)" *.dcm

Same as -e, but also searches in sequences and items.

💜 `-ep`, `--erase-private`

dcmodify -ep *.dcm

Deletes all private tags (i.e. tags having an odd group number) from all files matching *.dcm in the current directory.

⭐ `-gst`, `--gen-stud-uid`

dcmodify -gst file.dcm

This generates a new value for the StudyInstanceUID (0020,000d). Other UIDs are not modified!

🍓 `-gse`, `--gen-ser-uid`

dcmodify -gse file.dcm

This generates a new value for the SeriesInstanceUID (0020,000e). Other UIDs are not modified!

🔥 `-gin`, `--gen-inst-uid`

dcmodify -gin file.dcm

This command generates a new value for the SOPInstanceUID (0008,0018). The corresponding MediaStorageSOPInstanceUID (0002,0003) is adjusted to the new value automatically. Please note that it's not possible to avoid this metaheader update via the -nmu option.

🙈 `-nmu`, `--no-meta-uid`

dcmodify -m "SOPInstanceUID=[UID]" -nmu *.dcm

This will modify the SOPInstanceUID to the given [UID], but -nmu avoids, that dcmodify adjusts the MediaStorageSOPInstanceUID in the metaheader, too.

🧚 `-iff`, `--process-if`

dcmodify -iff "(0010,0010)" -m "(0010,0010)=A Name" file.dcm

If the tag (0010,0010) exists in the file, make the modification.

dcmodify -iff "!(0010,0010)" -i "(0010,0010)=A Name" file.dcm

If the tag (0010,0010) does not already exist in the file, make the insertion.

dcmodify -iff "(0010,0010)=Wrong Name" -m "(0010,0010)=A Name" file.dcm

If the tag (0010,0010) has the specific value "Wrong Name", make the modification.

dcmodify -iff "(0010,0010)" -iff "(0010,0010)!=A Name" -e "(0010,0010)" file.dcm

Remove the tag (0010,0010) if the tag exists and does not contain the value "A Name". Multiple conditions are combined with a logical AND.

dcmodify -iff "(0008,1111)[*].PatientName=A Name" -m "(0010,0010)=Another Name" file.dcm

If PatientName in all items of the sequence (0008,1111) are "A Name", make the modification.

dcmodify -iff "SOPInstanceUID=[UID]" -m "(0010,0010)=A Name" file.dcm

If the SOPInstanceUID equals [UID], make the modification. [UID] can also contain the UID keyword instead of the string of numbers.

This option also allows longer tag paths as demonstrated above for -i.

🚨 ERROR HANDLING 🚨

dcmodify tries executing each modify operation given on command line. If one returns an error, the others are being performed anyway. However in case of any error, the modified file is not saved, unless the --ignore-errors option is specified. If that option is selected, dcmodify also continues modifying further files specified on command line; otherwise dcmodify exits after the first file that had modification errors.

If the --ignore-missing-tags option is enabled, any modify or erase operations (i.e. not --insert) that fails because of a non-existing tag is treated as being successful. That does make sense if someone wants to be sure that specific tags are not present in the file or that — if they exist — that they are set to a specific value.

📝 LOGGING 📝

The level of logging output of the various command line tools and underlying libraries can be specified by the user. By default, only errors and warnings are written to the standard error stream. Using option --verbose also informational messages like processing details are reported. Option --debug can be used to get more details on the internal activity, e.g. for debugging purposes. Other logging levels can be selected using option --log-level. In --quiet mode only fatal errors are reported. In such very severe error events, the application will usually terminate. For more details on the different logging levels, see documentation of module "oflog".

In case the logging output should be written to file (optionally with logfile rotation), to syslog (Unix) or the event log (Windows) option --log-config can be used. This configuration file also allows for directing only certain messages to a particular output stream and for filtering certain messages based on the module or application where they are generated. An example configuration file is provided in <etcdir>/logger.cfg.

🖥️ COMMAND LINE 🖥️

All command line tools use the following notation for parameters: square brackets enclose optional values (0-1), three trailing dots indicate that multiple values are allowed (1-n), a combination of both means 0 to n values.

Command line options are distinguished from parameters by a leading '+' or '-' sign, respectively. Usually, order and position of command line options are arbitrary (i.e. they can appear anywhere). However, if options are mutually exclusive the rightmost appearance is used. This behavior conforms to the standard evaluation rules of common Unix shells.

In addition, one or more command files can be specified using an '@' sign as a prefix to the filename (e.g. @command.txt). Such a command argument is replaced by the content of the corresponding text file (multiple whitespaces are treated as a single separator unless they appear between two quotation marks) prior to any further evaluation. Please note that a command file cannot contain another command file. This simple but effective approach allows one to summarize common combinations of options/parameters and avoids longish and confusing command lines (an example is provided in file <datadir>/dumppat.txt).

🌱 ENVIRONMENT 🌱

The dcmodify utility will attempt to load DICOM data dictionaries specified in the DCMDICTPATH environment variable. By default, i.e. if the DCMDICTPATH environment variable is not set, the file <datadir>/dicom.dic will be loaded unless the dictionary is built into the application (default for Windows).

The default behavior should be preferred and the DCMDICTPATH environment variable only used when alternative data dictionaries are required. The DCMDICTPATH environment variable has the same format as the Unix shell PATH variable in that a colon (":") separates entries. On Windows systems, a semicolon (";") is used as a separator. The data dictionary code will attempt to load each file specified in the DCMDICTPATH environment variable. It is an error if no data dictionary can be loaded.

💖 And that’s the whole dcmodify(1) saga, bestie — version 3.7.1, stamped Sat Oct 17 2026 09:34:01. Go modify those DICOMs like the main character you are. 🎀✨

📦 where this page comes from

arch rolling: dcmtk 3.7.1-1 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms