Skip to main content

Troubleshooting nglview JavaScript Errors

  • Updated

Overview

 

We have received reports that nglview fails to run in the Matlantis environment, sometimes displaying an error screen. One cause of this issue is a version mismatch between the Python package (nglview) and the Jupyter Lab extension (nglview-js-widgets).

Error screen: 

Example error displayed after clicking:

Solutions

Solution 1: Uninstall manually installed nglview (Recommended)

If you do not require a specific nglview version, the best solution is to uninstall the manually installed nglview from all environments and use the default version provided by Matlantis.

  1. Launch a Notebook in every kernel (e.g., py39, py311, py313) and uninstall nglview.

    !pip uninstall nglview

    (※ Please run this in all kernels, including py313, py311, py39, and any custom venv environments.)

  2. Launch a single Notebook in any kernel and remove the associated labextensions.

    !rm -rf ~/.py39/share/jupyter/labextensions/nglview-js-widgets
!rm -rf ~/.py311/share/jupyter/labextensions/nglview-js-widgets
!rm -rf ~/.py313/share/jupyter/labextensions/nglview-js-widgets

    (※ Also remove this from any custom venv environments, if applicable.)

  3. Refresh the Matlantis screen. (If the issue persists, restart Matlantis.)
    This allows the default nglview to be used, resolving the error.

 

Solution 2: Unify the nglview version across all kernels

If you must install a specific version of nglview manually, you must install the exact same version in all kernels (py313, py311, py39, venv environments, etc.).

!pip install -U nglview==4.0.0

 

Background: How the Error Occurs

 

1. Separate Package Management

 

nglview consists of two components that are managed separately:

  • The Python library itself (installed in site-packages).
  • The JavaScript extension for display in Jupyter Lab (located at labextensions/nglview-js-widgets, hereafter widgets).

 

2. The site-packages Environments in Matlantis

 

The Matlantis environment has two types of site-packages locations:

  1. Common Packages (①): Shared by all users.
    • /usr/local/pyenv/versions/3.13.8/envs/python313/lib/python3.13/site-packages/
    • This location contains the default nglview v4.0.0.
  2. User Packages (②): Installed individually by the user.
    • /home/jovyan/.py313/lib/python3.13/site-packages/
    • If you manually install nglview (e.g., via the old pfcc_extras), your specified version is saved here and takes precedence over the common package (①).

 

3. Version Dependency of widgets

 

The widgets component is strongly dependent on the nglview Python library. They will not work correctly if their versions do not match.

Jupyter Lab only loads one version of the widgets upon startup (usually the one from the highest-priority kernel, like py313).

 

4. How the Bug Occurs

 

Due to these specifications, the problem occurs when different versions of nglview are used in different kernels.

For example: Imagine you manually installed nglview (②) in the py313 kernel but are using the default nglview (①) in the py311 kernel. When Jupyter Lab starts, it loads the widgets associated with py313. If you then try to run nglview in the py311 kernel, a version mismatch occurs between the nglview library (default) and the loaded widgets (manual), causing the error.

 

Note: If the issue is not resolved, please refer to this article to reset your Python environment.

Related articles