Python reference

dcmview-py is a subprocess wrapper and binary distribution path for the same Rust viewer. It is not a DICOM parsing library.

Signature

view(
    files,
    *,
    port=0,
    host="127.0.0.1",
    browser=True,
    tunnel=False,
    tunnel_host=None,
    tunnel_port=0,
    block=True,
    recursive=True,
    timeout=None,
    annotations=None,
    filters=None,
    vscode_bridge=True,
)

files accepts one str or path-like value, or an iterable of path-like values.

Parameters

Parameter	Default	Behavior
files	required	File or directory path, or an iterable of paths.
port	0	Forwards --port; zero selects an available port.
host	"127.0.0.1"	Forwards --host.
browser	True	False forwards --no-browser.
tunnel	False	Enables the Rust SSH helper.
tunnel_host	None	Required when tunnel=True.
tunnel_port	0	Forwarded port when tunneling; zero reuses the viewer port.
block	True	Wait for exit, or return a session handle.
recursive	True	False forwards --no-recursive.
timeout	None	Optional idle timeout in seconds.
annotations	None	Optional EMBED-style ROI CSV path.
filters	None	Iterable of FIELD=VALUE filters combined with AND semantics.
vscode_bridge	True	Allow a trusted active workspace bridge to own the session.

Return values

With block=True, a successful call returns None after the session exits.

With block=False, it returns one of:

• ShutdownHandle for a local subprocess; or
• BridgeShutdownHandle for a VS Code-managed session.

Both expose:

• .url -> str | None
• .stop(timeout=5.0) -> int
• context-manager entry and exit

For a local session, .stop() sends the platform’s graceful interrupt, then terminate and kill fallbacks if necessary. For a bridged session, it asks VS Code to stop and wait for the owned session.

Exceptions

Exception	Cause
ValueError	No file paths, or tunnel=True without tunnel_host.
TypeError	Invalid file, annotation, or filter argument types.
RuntimeError	Binary resolution or startup failed.
subprocess.CalledProcessError	The viewer returned a non-zero exit status.

A bridge error before VS Code captures the session falls back to a local subprocess. A failure while waiting for an already captured blocking session is raised; the wrapper does not start a duplicate viewer.

Binary resolution

The wrapper resolves the executable in this order:

1. DCMVIEW_BINARY, which must resolve to an existing file.
2. The platform binary bundled inside the installed wheel.
3. dcmview or dcmview.exe on PATH.

When launching directly, the wrapper first adds hidden --startup-json so it can parse the server URL reliably. It retries without that option for compatibility with an older binary that explicitly rejects the flag.

Runtime environment variables

Variable	Behavior
DCMVIEW_BINARY	Override executable path.
DCMVIEW_VSCODE_BYPASS=1	Disable bridge discovery.
DCMVIEW_VSCODE_BRIDGE_URL	Explicit extension-managed bridge URL.
DCMVIEW_VSCODE_BRIDGE_TOKEN	Bearer token for the explicit bridge.
DCMVIEW_VSCODE_BRIDGE_REGISTRY_DIR	Override out-of-band bridge registry location.
DCMVIEW_VSCODE_BRIDGE_DEBUG=1	Print bridge discovery diagnostics to stderr.
XDG_STATE_HOME	Preferred Unix base for bridge registry state when absolute.
XDG_RUNTIME_DIR	Legacy Unix registry fallback when absolute.

Bridge entries expire after three hours. On Unix, registry directories must be owned by the current user and must not be group- or world-writable.

See Launch dcmview from Python for complete examples.