How to view a molecule#

Goal#

Open a viewer on a Molecule object — overview of all supported backends.

Minimal example#

from moleculekit.molecule import Molecule

mol = Molecule("3PTB")

# Auto-detect the best available viewer
mol.view()

Parameters that matter#

Parameter

Type

Default

What it does

viewer

str

auto

"molstar", "vmd", or "pymol"

name

str or None

None

Display label for the molecule in the viewer

sel

str

None (all)

Atom selection to pass to the viewer

style

str or None

None

Representation style hint for compatible viewers

Common variations#

# Browser-based viewer (built in, no external install required)
mol.view(viewer="molstar")

# VMD desktop viewer
mol.view(viewer="vmd")

# PyMOL desktop viewer
mol.view(viewer="pymol")

Viewer auto-selection order#

When viewer= is not given, moleculekit picks a backend in this order:

  1. MOLECULEKIT_VIEWER environment variable (e.g. export MOLECULEKIT_VIEWER=molstar).

  2. moleculekit.config["viewer"] runtime setting.

  3. VMD found on $PATH.

  4. PyMOL found on $PATH.

  5. Molstar fallback (always available).

Molstar backend behaviour#

  • The first call to mol.view(viewer="molstar") starts an HTTP server on the first free port from 8765 onward and opens a browser tab. Subsequent calls (same or a different Molecule) push to the existing tab.

  • Updates propagate automatically: a daemon thread polls registered molecules every ~0.5 s and pushes changes via Server-Sent Events. There is no need to call .view() again after mutating a molecule.

  • Topology changes (mutation, filtering, bond edits) trigger a full rebuild in the viewer. Coordinate-only changes update in place without resetting the camera.

  • Multiple registered molecules appear in the slot sidebar at the bottom-right of the viewer with an eye icon (show/hide) and an × button (remove). Closing a slot removes it from the viewer; the Python Molecule object is unaffected.

  • Bond orders and per-atom formal charges are always rendered.

Gotchas#

  • VMD and PyMOL must be on $PATH for their respective backends to work.

  • The molstar backend opens a tab in the default web browser; headless environments cannot open a browser tab automatically.

  • Restarting the Python process invalidates the existing molstar browser tab — the page will show a “Server restarted — refresh page” banner. Reload the tab to connect to the new server.

  • Trajectories are sent to molstar in full. For very large trajectories (>~100 MB of coordinates) consider striding the frames yourself before calling .view().