Getting started

Install dcmview, open an approved DICOM file or study directory, and stop the temporary viewer when you are finished.

Choose an install channel

The Python package is the shortest supported path on Linux x64, macOS x64, macOS arm64, and Windows x64. Its wheel bundles the same Rust binary used by every other integration.

Environment	Supported install path
Linux x64	`dcmview-py` from PyPI or a GitHub Release archive
macOS x64 or arm64	`dcmview-py` from PyPI or a GitHub Release archive
Windows x64	`dcmview-py`, a GitHub Release archive, or the VS Code extension
VS Code on a supported host	`dcmview` from the VS Code Marketplace
Another platform	Build the Rust binary from source

You need Python 3.9 or later for the PyPI package.

Install the stable release

python -m pip install --user dcmview-py==0.4.1

The package installs two console commands, dcmview and dcmview-py. Use dcmview as the primary command.

If your shell cannot find a user-installed command, reopen the shell or add Python’s user script directory to PATH. See installation troubleshooting before installing another copy.

Verify the installation

dcmview --version

dcmview 0.4.1

You can also inspect the full command help:

dcmview --help

Inspect a first file

Choose a synthetic or properly authorized DICOM file already on your machine:

dcmview ./scan.dcm

dcmview binds an available loopback port, starts discovery, and opens the viewer in your default browser. The link it opens ends in #token=…, the session’s access token; the viewer removes it from the address bar once the page has loaded and keeps it for that tab. The first valid object can appear while a larger directory scan is still running.

For a directory, pass the directory path. Discovery is recursive by default:

dcmview ./study-directory

In the viewer:

Select a file or logical series in Explorer.
Use Left/Right arrows to move through frames. The mouse wheel zooms about the pointer.
Press W, then drag to change window and level; press P to pan or Z to zoom.
Move the cursor over the image to read the pixel’s stored, Modality, and real-world values.
Open Tags to inspect DICOM metadata.

Press Ctrl+C in the launching terminal to stop the server. There is no database or saved viewer session to clean up.

If a browser cannot open

Ask dcmview to print the URL instead:

dcmview --no-browser ./study-directory

dcmview: (on a remote server? run on your local machine: ssh -L <port>:localhost:<port> user@host)
dcmview: then open http://localhost:<port>/#token=<session-token>
dcmview: server running at http://127.0.0.1:<port>/#token=<session-token>
dcmview: press Ctrl+C to stop

Open the complete server running at link on the same machine, including its #token=… fragment. Every API request needs that token, so the address without the fragment shows a page that asks for the access link instead of your files. Paste the full link into the same tab to continue. If the files are on another server, follow the remote inspection guide instead of exposing the viewer publicly. On a server shared with other accounts, that guide also covers the private --unix-socket mode.

Options worth knowing early

Option or variable	Use it to
`--no-browser`	Print the link instead of opening a browser.
`--unix-socket PATH`	Serve through a private Unix socket on a shared Linux or macOS server.
`--cache-budget BYTES`	Lower frame cache memory on a small machine, for example `256MiB`.
`DCMVIEW_TOKEN`	Fix the access token for a script that calls the API.
`--no-token`	Turn the token check off behind a proxy that already authenticates.

The CLI reference gives the exact rules for each.