Jupyter

Some PyMOL functionality can be used inside Jupyter Notebooks. Since PyMOL's nature is primarily that of an application and not of a library, there are various ways to do PyMOL+Jupyter integration, each way with its own limitations.

Ways of Integration

Directly using the PyMOL API
- Running PyMOL and Jupyter in the same interpreter
  - Same thread (headless only)
  - Asynchronous thread (GUI possible)
- Running PyMOL standalone, with RPC communication (GUI possible)
Using third party libraries which add their own intermediate layer
- IPyMOL controls a PyMOL instance via RPC
- RDKit controls a PyMOL instance via RPC

Installation

If PyMOL and Jupyter should run in the same interpreter, they need to be installed into the same Python environment. RPC also works with two independent environments.

Incentive PyMOL

Install Miniconda or Anaconda (or grab a bundle from pymol.org which includes conda). Then install:

conda install jupyter schrodinger::pymol

Open-Source PyMOL

Compile and install PyMOL with the same Python that you use with Jupyter, into the same environment.

Example 1: Same interpreter, same thread

This example will render an image and display it inside the Jupyter notebook.

Open a notebook, then execute:

from pymol import cmd
cmd.fragment('ala')
cmd.orient()

# since PyMOL 2.5
cmd.ipython_image()

# before PyMOL 2.5
cmd.png('/tmp/foo.png', ray=1)
from IPython.display import Image
Image(filename='/tmp/foo.png')

Example 2: Same interpreter, asynchronous thread

Note: This doesn't work on macOS, see https://github.com/schrodinger/pymol-open-source/issues/28

This example will control a PyMOL window (see also stdout notice).

Open a notebook, then execute:

# open a PyMOL window
import sys
import pymol
_stdouterr = sys.stdout, sys.stderr
pymol.finish_launching(['pymol', '-q'])
sys.stdout, sys.stderr = _stdouterr

# load something into the PyMOL window
from pymol import cmd
cmd.fragment('ala')

Example 3: RPC

Launch PyMOL with the "-R" option:

pymol -R

Open a Python 3 notebook, then execute:

# load something into the PyMOL window
import xmlrpc.client as xmlrpclib
cmd = xmlrpclib.ServerProxy('http://localhost:9123')
cmd.fragment('ala')