Launch dcmview from Python

Launch the same v0.2.12 Rust viewer after Python code has selected the files or cases to inspect.

Install the wrapper

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

Supported wheels bundle the dcmview binary. The wrapper requires Python 3.9 or later.

Wait for the viewer to exit

The default call blocks until the viewer stops and returns None after a successful exit:

inspect_case.py

from dcmview_py import view

view("./scan.dcm")

Use a list to inspect multiple files or directories, and disable the automatic browser when working in a terminal or notebook:

inspect_study.py

from dcmview_py import view

view(
    ["./study", "./derived/segmentation.dcm"],
    browser=False,
    timeout=300,
    filters=["Modality=CT"],
)

timeout is an idle timeout: API or browser requests reset it.

Control a non-blocking session

Set block=False to receive a handle:

nonblocking.py

from dcmview_py import view

handle = view("./study", browser=False, block=False)
if handle is None:
    raise RuntimeError("expected a non-blocking handle")

print(handle.url)
return_code = handle.stop()

The URL can briefly be None if startup takes longer than the wrapper’s initial five-second wait. The background monitor continues watching and updates handle.url when the server reports it.

For deterministic cleanup, use the handle as a context manager:

context_managed.py

from dcmview_py import view

with view("./study", browser=False, block=False) as handle:
    print(handle.url)

The context manager calls stop() on exit. Local handles request graceful shutdown, then terminate and finally kill the subprocess only if it does not stop within the timeout.

Load annotations

annotations.py

from dcmview_py import view

view(
    "./study",
    annotations="./embed_annotations.csv",
    browser=False,
)

See the annotation guide for CSV shape and in-memory editing behavior.

Control VS Code routing

When an active dcmview VS Code bridge owns the current workspace, view() may open the session in a VS Code webview. The returned non-blocking handle then controls that VS Code-managed session through the same .url and .stop() interface.

Force a local subprocess when a browser window is preferable:

local_only.py

from dcmview_py import view

view("./study", vscode_bridge=False)

You can also set DCMVIEW_VSCODE_BYPASS=1 for the process environment.

Handle failures

• ValueError: no paths were supplied, or tunneling lacks tunnel_host.
• TypeError: a file, annotation, or filter value has the wrong type.
• RuntimeError: no usable binary was found or startup could not be established.
• subprocess.CalledProcessError: the viewer exited with a non-zero status.

Read the exact Python API reference for every parameter, binary resolution, and bridge environment variable.