Open DICOM data in VS Code or Cursor

Open local DICOM files and folders in a VS Code or Cursor webview backed by the same loopback dcmview server.

Install the extension

Install dcmview by publisher beatricebm from the VS Code Marketplace. Cursor users can install the same extension identifier from Open VSX. v0.4.1 bundles viewer binaries for Linux x64, macOS x64, macOS arm64, and Windows x64.

On another host platform, build or install a compatible binary and set dcmview.binaryPath to its absolute path.

Open a file or folder

In Explorer, right-click a DICOM file or directory and choose Open with dcmview. The extension starts dcmview --no-browser --port 0 on loopback and opens the viewer beside the current editor. The viewer’s API requires an access token, which the extension passes to the panel for you; there is no link to copy.

The viewer follows the editor’s color theme: light themes open it light, and dark and high-contrast themes open it dark. Switching themes updates open viewers without reloading them.

For files ending in .dcm, .dicom, or .ima, you can also use Reopen With… → dcmview. Set dcmview as the default editor for those patterns if desired. Use the Explorer context menu for extensionless DICOM files and directories.

Other commands in the Command Palette:

• dcmview: Open Workspace with dcmview opens a selected workspace folder.
• dcmview: Stop All dcmview Sessions stops extension-managed viewers.
• dcmview: Show Bridge Status reports the active terminal bridge.

Use terminal and Python routing

Every launch follows one rule. dcmview, dcmview-py, python -m dcmview_py, and dcmview_py.view() open in a VS Code webview when they run in an integrated terminal created after the extension activated, or when their working directory is inside an open workspace folder. The second case covers notebook kernels started from the workspace. Anywhere else the ordinary local viewer starts.

Terminal interception is controlled by dcmview.terminalInterception.enabled. Existing terminals are not retrofitted when the extension activates.

Bypass the bridge for one shell session:

export DCMVIEW_VSCODE_BYPASS=1
dcmview ./study

In Python, pass view(..., vscode_bridge=False) for one call.

A viewer that is slow to start in VS Code is waited for up to 120 seconds. A launch that reached the bridge but was not confirmed exits with an error instead of opening a second, local viewer. Stale bridge entries are probed before launch, so a port reused by another service does not block opening an image. If terminal or notebook launches stop opening in VS Code, update the extension: v0.3.0 no longer searches the registry locations used by extension builds older than 0.2.5.

Work over Remote-SSH

In a Remote-SSH window the extension runs beside the data and VS Code forwards the viewer’s port. The extension forwards the viewer’s origin and attaches the access token afterwards, so the token is preserved across port forwarding and the panel loads as it does locally. The extension’s output channel does not show the token.

Two things do not carry over from a terminal workflow:

• --unix-socket is not supported. Do not add it to dcmview.extraArgs; the extension needs an HTTP viewer URL and reports the launch as unsupported. A dcmview --unix-socket command typed in an integrated terminal runs the ordinary local viewer instead of opening a webview.
• A DCMVIEW_TOKEN exported in a terminal or set in a notebook is not forwarded to a viewer the extension manages. That viewer inherits the extension host’s environment and otherwise generates its own token.

Adjust settings

Setting	Default	Purpose
dcmview.binaryPath	""	Absolute viewer binary override.
dcmview.defaultRecursive	true	Recursively scan selected folders.
dcmview.extraArgs	[]	Extra CLI arguments placed before selected paths.
dcmview.startupTimeoutSeconds	20	Time allowed for the server to report its URL.
dcmview.terminalInterception.enabled	true	Route supported integrated-terminal launches into webviews.

Use CLI argument/value pairs as separate dcmview.extraArgs elements. Do not put selected paths there; the extension appends them.

Mask identifiers on a shared screen

Add --mask to dcmview.extraArgs so that viewers the extension starts are masked sessions:

settings.json

{
  "dcmview.extraArgs": ["--mask"]
}

A masked viewer panel is titled dcmview: masked session instead of the file name, and the viewer replaces patient identifiers in everything it displays. The Redact tool (X) covers burned-in pixel text, with or without masking.

The editor itself is not masked

Masking is a display aid inside the viewer page, not de-identification. VS Code’s own Explorer, the tab of a file opened in the DICOM custom editor, the terminal, and the viewer’s Directory view still show real folder and file names. Hide them before you share your screen.

See Share your screen for what masking replaces and what it does not cover.

For binary order and bridge variables, see the VS Code reference. For startup failures, see troubleshooting.