DCMTK commands for developers: a working reference

  • DCMTK provides command-line tools including echoscu, storescu, dcmsend, storescp, dcmrecv, dcmdump, dcmodify, and dcmconv.
  • echoscu sends a C-ECHO request to verify a DICOM endpoint accepts associations without sending patient data.
  • storescu sends named files in one association, while dcmsend adds directory scanning and a pass/fail summary.
  • storescp accepts common storage SOP classes by default, but dcmrecv needs an explicit profile to accept C-STORE.
  • dcmdump prints DICOM tag contents, dcmodify edits tag values, and dcmconv rewrites the transfer syntax.

DCMTK is a free, open-source set of command-line tools for testing and inspecting DICOM data. If you build software that talks to hospital scanners or a PACS, you’ll reach for it constantly — long after any GUI viewer stops being fast enough. This reference covers the eight commands you’ll use most. You’ll see how to send a test study, check that a listener answers, and read what’s actually inside a .dcm file. Every command below ran during this session, with real output. You see what success and failure actually look like, not just the documented happy path.

Flags stay mostly stable across DCMTK’s 3.6.x and 3.7.x release lines. Still, run --help on your own installed version first. A Linux distro package can lag a year or more behind the version tested here (DCMTK 3.7.0), and default behavior does change between major releases.

Installing DCMTK and checking your version

On macOS with Homebrew: brew install dcmtk. On Debian or Ubuntu: apt install dcmtk. Both put every tool in this article on your PATH.

Check the version before you start:

$ echoscu --version
$dcmtk: echoscu v3.7.0 2025-12-15 $

Every tool in the suite reports its version this way. If a command behaves differently from this article, check the version first.

Quick reference

Command Role SOP class it exercises
echoscu Ping a DICOM endpoint Verification (C-ECHO)
storescu Send named files Storage (C-STORE)
dcmsend Send files or folders, with a summary report Storage (C-STORE)
storescp Receive files, storage classes on by default Storage (C-STORE)
dcmrecv Receive files, needs an explicit profile for storage Storage (C-STORE)
dcmdump Print every tag in a file — (offline, no network)
dcmodify Edit tag values in place — (offline, no network)
dcmconv Rewrite the transfer syntax — (offline, no network)

echoscu: checking a DICOM endpoint is alive

echoscu sends a C-ECHO request — DICOM’s version of a ping. It proves an endpoint accepts associations and answers, without sending patient data.

$ echoscu -aec TESTSCP -aet TESTCLIENT localhost 11113 -v
I: Requesting Association
I: Association Accepted (Max Send PDV: 16372)
I: Sending Echo Request (MsgID 1)
I: Received Echo Response (Success)
I: Releasing Association

-aec sets the called Application Entity (AE) title — the name of the service you’re connecting to. -aet sets your own, calling, AE title. Most listeners check at least one of these before they accept a connection. Get them right before you assume the network itself is broken.

One more common trap: the standard DICOM port is 104. On Linux and macOS, binding to any port below 1024 needs root privileges. Test tools almost always listen on a high port instead, such as 11112 or 11113, for exactly this reason.

If echoscu hangs instead of failing fast, the connection is probably stuck waiting on a firewall that silently drops packets rather than rejecting them. Add -to <seconds> to set a connection timeout, so a hung test fails in a predictable time instead of running forever.

storescu and dcmsend: sending a study

Both tools send DICOM files with a C-STORE request, but they solve slightly different problems.

storescu sends one or more named files in a single association:

$ storescu -aec TESTSCP -aet TESTCLIENT localhost 11113 -v synthetic-test.dcm
I: checking input files ...
I: Requesting Association
I: Association Accepted (Max Send PDV: 16372)
I: Sending file: synthetic-test.dcm
I: Sending Store Request (MsgID 1, SC)
I: Received Store Response (Success)
I: Releasing Association

dcmsend does the same job. It adds directory scanning and a pass/fail summary:

$ dcmsend -aec TESTSCP -aet TESTCLIENT localhost 11113 -v synthetic-test.dcm
I: sending SOP instances ...
I: Sending C-STORE Request (MsgID 1, SC)
I: Received C-STORE Response (Success)
I: Releasing Association
I:
I: Status Summary
I: --------------
I: Number of associations   : 1
I: Number of pres. contexts : 1
I: Number of SOP instances  : 1
I: - sent to the peer       : 1
I:   * with status SUCCESS  : 1

Reach for storescu in a quick one-off test. Reach for dcmsend when you’re replaying a whole study folder and want a count of what actually succeeded. dcmsend also takes a directory instead of a filename, but only with +sd (--scan-directories) added. Pass it a bare directory without that flag, and it does nothing, since scanning isn’t the default.

storescp and dcmrecv: receiving a study

Both act as a C-STORE receiver, but they don’t behave the same way out of the box. This trips people up the first time they switch between them.

storescp accepts common storage SOP classes by default:

$ storescp -aet TESTSCP --output-directory ./incoming -v 11113

Send it a file with storescu, and it writes the instance straight to --output-directory. No extra configuration needed — except that the directory must already exist. storescp will not create it for you, and a missing directory fails silently enough that it’s worth checking first if received files never show up.

dcmrecv only supports the Verification SOP class (C-ECHO) until you give it an explicit profile:

$ dcmrecv -v 11114
...
I: Association Received localhost: TESTCLIENT -> ANYTHING
I: No Acceptable Presentation Contexts
I: Refusing Association (no acceptable presentation contexts)

An echoscu ping against the same port succeeds. C-ECHO is the one SOP class dcmrecv always supports. To make dcmrecv accept a C-STORE, pass it -xf <config-file>,<profile> naming the SOP classes and transfer syntaxes you want. If you want something that stores files with no setup, start with storescp. dcmrecv’s extra profile step buys you a smaller, more auditable list of what your test receiver will accept.

dcmdump: reading what’s inside a file

dcmdump prints every tag in a DICOM file in a human-readable form:

$ dcmdump synthetic-test.dcm
(0002,0010) UI =LittleEndianExplicit                    #  20, 1 TransferSyntaxUID
(0008,0016) UI =SecondaryCaptureImageStorage             #  26, 1 SOPClassUID
(0010,0010) PN [Test^Synthetic]                          #  14, 1 PatientName
(0028,0010) US 4                                         #   2, 1 Rows
(0028,0011) US 4                                         #   2, 1 Columns

Reach for this first whenever behavior looks wrong. Before you suspect the network, the sender’s software, or your own parsing code, dump the file and check the tag values match what you expect. It’s the fastest way to rule out an entire category of bugs in seconds.

On a large file, scrolling through every tag is slow. Use +P <tag> to print just the one you care about:

$ dcmdump +P PatientName synthetic-test.dcm
(0010,0010) PN [Test^Synthetic]                          #  14, 1 PatientName

+P accepts either the numeric tag (gggg,eeee) or the dictionary name, and you can repeat it to check several tags in one call.

dcmodify and dcmconv: changing tags and transfer syntax

dcmodify edits attribute values in place. This is how you build synthetic test data without a full authoring tool:

$ dcmodify -i "(0010,0010)=Anonymized^Test" synthetic-test.dcm
$ dcmdump synthetic-test.dcm | grep PatientName
(0010,0010) PN [Anonymized^Test]                         #  16, 1 PatientName

dcmconv rewrites the file’s transfer syntax — the byte-level encoding — without touching tag values:

$ dcmconv --write-xfer-implicit synthetic-test.dcm implicit-test.dcm

Use this to reproduce transfer-syntax-specific bugs. Take a file that works and convert it to Implicit VR Little Endian, or to a compressed syntax your decoder handles. Then check whether the failure follows the encoding, not the content.

Chaining these into a five-minute smoke test

You rarely run these commands in isolation. A typical local check, before you point anything at a real hospital feed, looks like this:

  1. Start a receiver: storescp -aet TESTSCP --output-directory ./incoming -v 11113.
  2. Confirm it answers: echoscu -aec TESTSCP -aet TESTCLIENT localhost 11113 -v.
  3. Send a test file: storescu -aec TESTSCP -aet TESTCLIENT localhost 11113 -v test.dcm.
  4. Confirm it arrived intact: dcmdump ./incoming/<received-file>.

If step 2 fails, the problem is the endpoint or the network, not your test data. If step 2 succeeds but step 3 fails, compare the AE titles and SOP classes each side actually offered. Most storescp/dcmrecv rejections trace back to a mismatch there, not to a broken network path.

When a command doesn’t behave as documented

Two habits save the most time here. First, run --help on the exact binary you installed, not the one from a blog post. Second, add -v for verbose output, or -d for full debug output, before you assume a tool is broken. DCMTK’s own log lines usually name the exact reason an association failed, the way the dcmrecv example above did.

If an association fails against a real hospital sender rather than a local test, the diagnostic codes go deeper than this reference covers. That’s its own topic — real senders bring their own quirks around AE title casing, presentation-context limits, and vendor-specific SOP classes that no local smoke test will surface. For the protocol these commands exercise, see DICOM C-ECHO: verification and connectivity testing and what is a DICOM Application Entity (AE) title?. Once your local tests pass, connect a real sender following the quickstart.

Dicomly builds infrastructure for healthcare software teams that receive DICOM studies from hospitals. Why we built Dicomly →

Sources

  1. OFFIS DCMTK — Open Source DICOM Toolkit (github.com)
  2. DICOM Standard Part 4 (PS3.4, Annex B — Storage Service Class) (dicom.nema.org)
  3. DICOM Standard Part 7 (PS3.7, Chapter 9 — DIMSE-C Service Protocol) (dicom.nema.org)
  4. DICOM Standard Part 8 (PS3.8, Chapter 9 — Network Communication Support for Message Exchange) (dicom.nema.org)

Start receiving DICOM today.

Early access. No credit card. First endpoint free.