py3Dmol

Common errors

• blank output

  cause Often caused by browser caching an older version of the 3Dmol.js JavaScript library, or incompatibility with older JupyterLab versions' stricter security policies for JavaScript injection.
  fix Clear your browser's cache, especially for Chrome. Restart your Jupyter Notebook server. If using JupyterLab, ensure all Jupyter/widget extensions are up-to-date.

• Error: Kernel message validation error: Missing property 'metadata'

  cause This error typically occurs in specific Jupyter environments (like JupyterLite) where the display message content, generated by `py3Dmol`, is not resilient to missing metadata properties expected by the kernel's message validation.
  fix This issue was often addressed by updates in the Jupyter environment (e.g., JupyterLite's kernel to ensure metadata is always included in display messages). Ensure your Jupyter environment is up-to-date. If the problem persists in a custom setup, it might indicate a need to ensure metadata is present in `IPython.display.publish_display_data()` calls.

Warnings

• breaking The underlying 3Dmol.js library (version 2.0.0, released around late 2022/early 2023) introduced minor breaking changes in its `GLModel` API. Functions that previously required a viewer argument (e.g., `vibrate`) no longer do, as models now intrinsically track their viewer. This caused initial compatibility issues with py3Dmol versions.
  Fix: Ensure you are using `py3Dmol` version 2.0.0.post1 or newer. If experiencing blank output, clear browser cache or restart Jupyter to ensure the latest JavaScript is loaded.
• gotcha py3Dmol widgets are static; there is only one-way communication from Python to the viewer. While the embedded 3D viewer is interactive in the browser (e.g., rotating, zooming), any changes made directly in the viewer UI are not communicated back to the Python kernel. This means viewer state cannot be directly read or manipulated by Python after initial rendering without re-rendering.
  Fix: Plan your visualization logic entirely within Python code to set up the initial display and styling. For complex interactive analysis requiring bidirectional communication, consider alternative libraries or custom Jupyter widget development with more advanced event handling.
• gotcha Users may encounter blank output in Jupyter notebooks or JupyterLab, particularly after updates or in specific browser environments (e.g., Chrome). This can be due to browser caching old JavaScript files or compatibility issues with older JupyterLab security settings.
  Fix: Try clearing your browser's cache, restarting the Jupyter server, or running `jupyter nbextension enable --py --sys-prefix py3dmol` and `jupyter labextension install @jupyter-widgets/jupyterlab-manager 3dmol/py3dmol` if using JupyterLab and encountering issues with widgets not rendering.

Install

• pip install py3Dmol Install latest version

Imports

• view

  import py3Dmol
  view = py3Dmol.view(...)

  The primary entry point is the `view` object, instantiated directly from the top-level `py3Dmol` module.

Quickstart

Initializes a 3Dmol viewer, loads a protein structure (PDB ID: 1ubq), styles it as a spectrum-colored cartoon, zooms to fit, and displays the interactive viewer in a Jupyter notebook cell.

import py3Dmol

# Create a viewer instance and load a PDB structure by query
view = py3Dmol.view(query='pdb:1ubq')

# Set a cartoon style with spectrum coloring
view.setStyle({'cartoon':{'color':'spectrum'}})

# Zoom to fit the entire molecule
view.zoomTo()

# Display the visualization in the notebook
view