dcmview is a fast, temporary DICOM viewer for research and development work.
Point it at one or more DICOM files from the command line or Python, and it
starts a local browser viewer for images, tags, cine playback, and rectangular
ROI annotations. Stop the process and the server is gone.
The main problem it solves is remote-server inspection. Medical imaging research
often happens where the data already live: an SSH session, a shared compute
server, or a locked-down institutional network. Viewing those images usually
means choosing between slow notebook plots, setting up a web viewer on the
server, opening firewall ports, or uploading data and annotations into a
third-party cloud tool. dcmview keeps the workflow local to the machine with
the files: start the viewer, forward the loopback port over SSH when needed, and
inspect the study in seconds.
dcmview is intended for developer and research inspection on secure networks,
not clinical diagnosis. Avoid public-facing server binds; use the default
loopback binding and SSH forwarding for remote workflows.
- Inspect DICOM files where they already are, including remote servers.
- Avoid notebook-based frame rendering for multi-frame studies.
- Keep data off third-party viewers when all you need is quick review.
- Open a browser UI with familiar viewer tools: pan, zoom, scroll, window/level, flips, rotation, tags, and cine playback.
- Load, edit, and export rectangular ROI annotations without modifying source DICOM files.
- Use the same tool from a shell command, Python script, notebook, or VS Code.
- Run as an ephemeral server with no database, config file, or persistent state.
The current public install channels are the Python package, GitHub Releases, and the VS Code Marketplace extension:
| Platform | Recommended channel | Notes |
|---|---|---|
| Linux x64 | dcmview-py or GitHub Releases |
PyPI wheels bundle the dcmview binary. |
| macOS x64 | dcmview-py or GitHub Releases |
PyPI wheels bundle the dcmview binary. |
| macOS arm64 | dcmview-py or GitHub Releases |
PyPI wheels bundle the dcmview binary. |
| Windows x64 | dcmview-py, GitHub Releases, or VS Code Marketplace |
PyPI wheels bundle dcmview.exe. |
| VS Code | VS Code Marketplace | The extension bundles platform-specific binaries for supported hosts. |
| Other platforms | Source build | Build the Rust binary locally and point wrappers at it when needed. |
Install the Python package:
python -m pip install --user dcmview-py
dcmview --helpThe package installs both dcmview and dcmview-py; dcmview is the primary
command. If you are using an unsupported platform or a local debug binary, set
DCMVIEW_BINARY to an absolute path to a compatible dcmview executable.
Homebrew distribution is planned for the v0.2.7 release but is not configured
yet. Until then, use PyPI, the VS Code extension, GitHub Releases, or a source
build.
Source builds are available for contributors and unsupported platforms:
cargo install --path .Build prerequisites for source installs:
- Rust stable 1.75+
- Node.js 18+ and npm at build time
sshonPATHonly when using SSH forwarding helpers
If install or binary discovery fails, see the troubleshooting guide. For all CLI, Python, VS Code, and environment settings, see the configuration reference. For the full documentation map, see the documentation index.
Open one file:
dcmview ./scan.dcmScan a study directory recursively:
dcmview ./study_dirRun without opening a browser, useful on a remote server:
dcmview --no-browser ./study_dirWhen ready, dcmview prints a URL:
dcmview: server running at http://127.0.0.1:<port>
Press Ctrl+C to stop the server.
If startup reports skipped files, no valid DICOM files, a port conflict, or a browser launch failure, see the troubleshooting guide.
The safest default is to keep dcmview bound to loopback on the remote machine
and access it through SSH port forwarding. dcmview is intended for research
and development use on secure networks; do not expose the server directly to a
public network.
On the remote server:
dcmview --no-browser --port 8888 /path/to/dicom_or_study_dirOn your local machine:
ssh -L 8888:localhost:8888 user@remote-serverThen open:
http://localhost:8888
You can also let dcmview use an auto-assigned port by omitting --port; copy
the printed port into your SSH command. The optional --tunnel flags are
available for environments where the dcmview process can start the SSH helper
itself.
The HTTP server is unauthenticated. It binds to 127.0.0.1 by default. If you
bind to 0.0.0.0 or another public interface, use your own network access
controls. Anyone who can reach the server may be able to access image pixels,
DICOM tags, file paths, patient identifiers, study identifiers, and in-memory
annotations.
dcmview-py is a small subprocess wrapper around the Rust binary. It is useful
when a script or notebook has already selected the cases to inspect. For the
full parameter reference, lifecycle details, VS Code bridge behavior, and
notebook-oriented examples, see the Python reference.
from dcmview_py import view
# Blocking call; returns when dcmview exits.
view(["./scan.dcm"], browser=False, timeout=300)
# Non-blocking call.
handle = view(["./study_dir"], browser=False, block=False)
print(handle.url)
handle.stop()Context manager:
from dcmview_py import view
with view(["./study_dir"], browser=False, block=False) as handle:
print(handle.url)The module CLI mirrors the Rust options:
python -m dcmview_py --no-browser --timeout 120 ./study_dirThe VS Code extension opens DICOM files or folders in a webview backed by the
same local dcmview server. It can also intercept dcmview, dcmview-py, and
python -m dcmview_py launches from new integrated terminals so terminal-based
workflows appear inside VS Code.
See the VS Code extension README for supported platforms, settings, terminal interception behavior, and local testing notes.
The embedded browser viewer includes:
- File tabs labeled from
PatientID,Modality, andStudyDatewhen present. - Canvas-based image viewing with pan, zoom, scroll, window/level, reset, horizontal/vertical flips, and 90-degree rotation.
- Window presets including DICOM defaults, full dynamic range, and common CT presets.
- Multi-frame controls with previous/next, cine playback, FPS selection, loop, and sweep.
- Lazy DICOM tag browsing with filtering, sequence expansion, binary length display, resizable columns, and click-to-copy values.
- Rectangular ROI annotation display and editing, including draw, select, move, resize, delete, frame scoping, and CSV export.
Common shortcuts:
| Action | Shortcut |
|---|---|
| Previous/next frame | Left/Right arrows or [ / ] |
| Play/pause cine | Space |
| Window/level tool | W |
| Pan tool | P |
| Zoom tool | Z |
| Scroll tool | S |
| ROI tool | R |
| Reset viewport | Double-click |
Right-drag always zooms, middle-drag always pans, the wheel scrolls frames, and Ctrl/Cmd+wheel zooms.
--annotations loads an EMBED-style rectangular ROI CSV into memory:
dcmview --annotations ./embed_annotations.csv ./study_dirdcmview never modifies the input CSV or DICOM files. Viewer edits stay in
memory and can be downloaded with Export ROIs. For the required columns,
coordinate format, frame scoping rules, validation behavior, and examples, see
the annotation reference.
dcmview [OPTIONS] <PATH> [PATH ...]
python -m dcmview_py [OPTIONS] <PATH> [PATH ...]
The Python module CLI forwards the same options to the underlying dcmview
binary. Run dcmview --help or python -m dcmview_py --help for command-line
help. For Python wrapper parameters, VS Code settings, environment variables,
filter fields, hidden integration flags, and binary resolution order, see the
configuration reference and
Python reference.
The browser UI uses a small local HTTP API. This API is internal to the viewer
and is not a stable public integration surface; use it only for dcmview
debugging, smoke tests, and local automation.
See the internal API reference for endpoint summaries, progressive scan fields, polling guidance, cache headers, transfer syntax behavior, raw-frame metadata headers, annotation endpoints, and error semantics.
Production builds do not enable cross-origin browser API access for external
debugging tools. To debug the viewer API from another browser origin, build with
cargo build --features debug-api; this enables permissive CORS and prints a
build warning. Do not enable debug-api outside dcmview debugging contexts.
For local development, install frontend dependencies, run the Rust backend, and optionally start the standalone Vite frontend:
npm --prefix frontend ci
dcmview --no-browser --host 127.0.0.1 --port 8888 tests/fixtures
npm --prefix frontend run devCommon checks:
cargo fmt --all
DCMVIEW_SKIP_FRONTEND_BUILD=1 cargo check --locked
cargo test --locked
npm --prefix frontend run typecheckSee the development reference for source builds, frontend proxy behavior, fixture policy, test commands, architecture notes, and cache budget guidance.
Use GitHub issues for DICOM compatibility problems, install failures, and feature requests. Do not attach DICOM files, screenshots, logs, paths, patient identifiers, or other sensitive information unless you have fully de-identified them and have approval to share them publicly.
Before filing an issue, check the troubleshooting guide for common install, startup, decode, tunnel, VS Code, and annotation CSV problems.
Report suspected security vulnerabilities privately to the maintainers before public disclosure; see SECURITY.md.
dcmview is not for clinical use, clinical diagnosis, or clinical
decision-making.
MIT