py3dmol

library2.5.5pypypi✓ verified 87d ago

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.

ai-ml

pip install py3Dmol

package ↗homepage ↗

INSTALL

IMPORT

SIG · PY3DMOL

py3dmol

ai-mlpythonv2.5.5

Install

1.5s avg

Import

109ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.5.5 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.920 runs

installs and imports cleanly · install 0.0s · import 0.114s · 17.8MB

glibc

py 3.10–3.920 runs

installs and imports cleanly · install 1.5s · import 0.104s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

view

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

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

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

Debug

Known issues

breakingThe 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.

affects: py3Dmol < 2.0.0.post1, and initial releases of 3Dmol.js 2.0.0

gotchapy3Dmol 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.

affects: All versions

gotchaUsers 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.

affects: All versions, especially during or after upgrades.

Errors

Common errors & fixes

blank output

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'

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.

Upgrade

Version history

2.5.5latest on PyPI · released May 23, 2026

Audit

Dependencies

ipythonrequiredRequired for Jupyter Notebook integration and display as an IPython widget.

ipywidgetsrequiredRequired for interactive Jupyter widget functionality.

Agent activity

12 hits · last 30 days

node

Resources

packagehttps://pypi.org/project/py3dmol/ ↗

homepagehttps://3dmol.org ↗