{"id":7532,"library":"py3dmol","title":"py3Dmol","description":"py3Dmol is an IPython interface for embedding 3Dmol.js views in Jupyter notebooks. It enables dependency-free interactive molecular visualization, as a minified version of the 3Dmol.js library is included directly. It supports rendering various molecular objects and is currently at version 2.5.4, with active development under the 3Dmol.js ecosystem.","status":"active","version":"2.5.4","language":"en","source_language":"en","source_url":"https://github.com/3dmol/3Dmol.js","tags":["Jupyter","visualization","chemistry","biology","molecular","3D","widget"],"install":[{"cmd":"pip install py3Dmol","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required for Jupyter Notebook integration and display as an IPython widget.","package":"ipython","optional":false},{"reason":"Required for interactive Jupyter widget functionality.","package":"ipywidgets","optional":false}],"imports":[{"note":"The primary entry point is the `view` object, instantiated directly from the top-level `py3Dmol` module.","symbol":"view","correct":"import py3Dmol\nview = py3Dmol.view(...)"}],"quickstart":{"code":"import py3Dmol\n\n# Create a viewer instance and load a PDB structure by query\nview = py3Dmol.view(query='pdb:1ubq')\n\n# Set a cartoon style with spectrum coloring\nview.setStyle({'cartoon':{'color':'spectrum'}})\n\n# Zoom to fit the entire molecule\nview.zoomTo()\n\n# Display the visualization in the notebook\nview","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"py3Dmol < 2.0.0.post1, and initial releases of 3Dmol.js 2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, especially during or after upgrades."}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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.","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.","error":"blank output"},{"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.","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.","error":"Error: Kernel message validation error: Missing property 'metadata'"}]}