Installation | Example | Usage | Command line | API doc | Interface classes | Website | GUI | Acknowledgment

Binder DOI Build Status bioconda-badge Coverage Status

An IPython/Jupyter widget to interactively view molecular structures and trajectories. Utilizes the embeddable NGL Viewer for rendering. Support for showing data from the file-system, RCSB PDB, simpletraj and from objects of analysis libraries mdtraj, pytraj, mdanalysis, ParmEd, rdkit, ase, HTMD, biopython, cctbx, pyrosetta, schrodinger’s Structure

Should work with Python 2 and 3. If you experience problems, please file an issue.

Ask question about usage? Please post here




Released version

  • Available on bioconda channel

    conda install nglview -c bioconda
    # might need: jupyter-nbextension enable nglview --py --sys-prefix
    # if you already installed nglview, you can `upgrade`
    conda upgrade nglview --force
    # might need: jupyter-nbextension enable nglview --py --sys-prefix
  • Available on PyPI

pip install nglview==1.0.b2
jupyter-nbextension enable nglview --py --sys-prefix

Version Compatibility

nglview ipywidgets
< 1.0 5.2.2
1.0 7.0


If you are using notebook v5.0, you need to increase the iopub_data_rate_limit to visualize big structure (e.g: solvated system)

jupyter notebook --NotebookApp.iopub_data_rate_limit=10000000

Development version

Requirement: ipywidgets >= 7.0.0, notebook >= 4.2

The development version can be installed directly from github:

notebook user

git clone
cd nglview
python install

# if you edit files in ./js folder, make sure to rebuild the code
cd js
npm install

# probably need to activate widgetsnbextension
# python -m ipykernel install --sys-prefix
# jupyter nbextension enable --py --sys-prefix widgetsnbextension
# jupyter nbextension enable --py --sys-prefix nglview

# tested with ipywidgets 5.2.2, notebook 4.2.1

jupyterlab user

HIGHLY EXPERIMENTAL. Things might not work as you are expecting.

# Please read its content before running
source devtools/


Showcase from users

Please check user examples. Feel free to contribute.


Open a notebook

jupyter notebook

and issue

import nglview
view = nglview.show_pdbid("3pqr")  # load "3pqr" from RCSB PDB and display viewer widget

A number of convenience functions are available to quickly display data from the file-system, RCSB PDB, simpletraj and from objects of analysis libraries mdtraj, pytraj, mdanalysis, ParmEd, rdkit, HTMD, biopython.

Function Description
show_file(path) Shows any NGL supported file formats (pdb, gro, mol2, sdf, dx, ..) in path
show_pdbid(pdbid) Shows pdbid fetched from RCSB PDB
show_simpletraj(struc_path, t raj_path) Shows structure & trajectory loaded with simpletraj
show_mdtraj(traj) Shows MDTraj trajectory traj
show_pytraj(traj) Shows PyTraj trajectory traj
show_parmed(structure) Shows ParmEd structure
show_mdanalysis(univ) Shows MDAnalysis Universe or AtomGroup univ
show_rdkit(mol) Shows rdkit rdkit.Chem.rdchem.Mol
show_ase(atoms) Shows ase Atoms
show_asetraj(traj) Shows ase trajectory traj
show_htmd(mol) Shows HTMD Molecules
show_biopython(mol) Shows Biopython structural entities
show_iotbx(mol) Shows cctbx's iotbx structure
show_rosetta(pose) Shows pyrosetta's Pose



view.add_representation(repr_type='cartoon', selection='protein')

# or shorter
view.add_surface(selection="protein", opacity=0.3)

# specify color
view.add_cartoon(selection="protein", color='blue')

# specify residue
view.add_licorice('ALA, GLU')

# clear representations

# update parameters for ALL cartoons of component 0 (default)
view.update_cartoon(opacity=0.4, component=0)

# remove ALL cartoons of component 0 (default)
view.remove_cartoon(opacity=0.4, component=0)

And many more, please check NGL website

Representations can also be changed by overwriting the representations property of the widget instance view. The available type and params are described in the NGL Viewer documentation.

view.representations = [
    {"type": "cartoon", "params": {
        "sele": "protein", "color": "residueindex"
    {"type": "ball+stick", "params": {
        "sele": "hetero"

The widget constructor also accepts a representation argument:

initial_repr = [
    {"type": "cartoon", "params": {
        "sele": "protein", "color": "sstruc"

view = nglview.NGLWidget(struc, representation=initial_repr)


# set the frame number
view.frame = 100
# parameters for the NGL stage object
view.parameters = {
    # "percentages, "dist" is distance too camera in Angstrom
    "clipNear": 0, "clipFar": 100, "clipDist": 10,
    # percentages, start of fog and where on full effect
    "fogNear": 0, "fogFar": 100,
    # background color
    "backgroundColor": "black",

# note: NGLView accepts both origin camel NGL keywords (e.g. "clipNear")
# and snake keywords (e.g "clip_near")
# parameters to control the `delay` between snapshots
# change `step` to play forward (positive value) or backward (negative value)
# note: experimental code
view.player.parameters = dict(delay=0.04, step=-1)
# update camera type = 'orthographic'
# change background color
view.background = 'black'


# adding new trajectory
# traj could be a `pytraj.Trajectory`, `mdtraj.Trajectory`, `MDAnalysis.Universe`,
# `parmed.Structure`, `htmd.Molecule` or derived class of `nglview.Trajectory`

# change representation
view.trajectory_0.add_cartoon(...) # equal to view.add_cartoon(component=0)
view.trajectory_1.add_licorice(...) # equal to view.add_licorice(component=1)

Add extra component

# Density volumes (MRC/MAP/CCP4, DX/DXBIN, CUBE)
# Or adding derived class of `nglview.Structure`

# add component from url
# NOTE: Trajectory is a special case of component.


# coot mouse style (

Interaction controls

Display more than two widgets

# 1st cell
import ipywidgets
vbox = ipywidgets.VBox([view1, view2])
vbox # display

# 2nd cell

Show GUI

Notes: Unstable feature. See also

Movie making

Notes: Unstable feature.

from import MovieMaker
movie = MovieMaker(view, output='my.gif')

Embed widget


Command line

# open a notebook and import nglview

# Require installing pytraj (PR for other backends is welcome)
# open notebook, load `my.pdb` to pytraj's trajectory then display `view`
nglview my.pdb

# load density data
nglview my.ccp4

# open notebook, create trajectory with given topology `my.parm7` and trajecotry file ``,
# then display `view`
nglview my.parm7 -c

# load all trajectories with filename ending with 'nc'
# make sure to use quote " "
nglview my.parm7 -c "*.nc"

# open notebook, copy content from `` then execute it

# open notebook and execute 1st cell
nglview mynotebook.ipynb

# create a remote notebook
# just follow its instruction
nglview my.pdb --remote
nglview my.parm7 -c --remote
nglview mynotebook.ipynb --remote

# demo (don't need pytraj)
nglview demo

# disable autorun the 1st cell of the notebook
nglview my.pdb --disable-autorun

# specify web browser
nglview my.pdb --browser=google-chrome




Join us here

Projects using NGLView

(Feel free to make a PR to add/remove your project here)

  • AMBER - A package of programs for molecular dynamics simulations of proteins and nucleic acids
  • mbuild - A hierarchical, component based molecule builder
  • deepchem - Deep-learning models for Drug Discovery and Quantum Chemistry
  • htmd - High throughput molecular dynamics simulations
  • Moleidoscope - Molecular kaleidoscope
  • ssbio - Tools for enabling structural systems biology
  • hublib - hublib is a Python library for the HUBzero science gateway platform.
  • molPX: ipython API to visualize MD-trajectories along projected trajectories
  • nanoribbon
  • ase: Atomic Simulation Environment
  • pida: Software for analyzing multiple protein-protein interaction docking solutions,
  • pytim
  • MobleyLab/drug-computing Educational materials for, and related to, UC Irvine’s Drug Discovery Computing Techniques course.



Generally MIT, see the LICENSE file for details.