Skip to main content

View molecules in the IPython notebook.

Project description


An embeddable webGL molecule viewer and file format converter.


* [IPython notebook](
* [metal-organic frameworks](


The IPython notebook is an open-source tool poised to replace MATLAB in many
applications. As a scientist of sorts, I'm all about it. Therefore, I made
handles to use imolecule with the notebook. Install through pip:

pip install imolecule

Open a new notebook and test the setup by typing:

import imolecule

into a notebook cell. This should convert, optimize and draw the specified
SMILES structure (in this case, penicillin) into the notebook.

Note that this requires Open Babel to function. If you do not have Open Babel,
see below for installation details.

The drawer can handle any format specified [here](,
and can be set up to better handle different use cases. Check out the docstrings
associated with the IPython interface for more.


If you want to run the file format converter on
your own computer, install the library with:

pip install imolecule

Then run from the command line with:


The default site allows for loading molecules via a simple file drag-and-drop
interface. Drag a file to anywhere in the browser and drop to load. This
interface communicates with openbabel via websocket, so most file formats should
work. Be sure to set the extensions of your files to their data type (ie. "mol",
"pdb", etc.) for format inference to work properly.

If you have an existing web server, tornado can be easily switched out for
other libraries. If you want to use imolecule as a starting point for a
broader user interface, the server is written to be extensible. In both cases,
read through the source code - it's surprisingly short.


Start by downloading the minified javascript file:


Include this file alongside [jQuery]( in your project, and then use with:


where `'my-selector'` is where you want to place imolecule, and `myMolecule` is
an object. See below for more on the object structure, or just check out the
included examples. The `imolecule.create()` method takes a few optional parameters,
specifying a few common drawing and camera types.

options = {
drawingType: "ball and stick", // Can be "ball and stick", "wireframe", or "space filling"
cameraType: "perspective", // Can be "perspective" or "orthogonal"
shader: "toon" // three.js shader to use, can be "toon", "basic", "phong", or "lambert"

Molecule Data Format

At its core, imolecule takes input chemical structures as javascript objects.
As an example, consider benzene:

atoms: [
{ element: "C", location: [ -0.762160, 1.168557, 0.022754 ] },
{ element: "C", location: [ 0.631044, 1.242862, -0.013022 ] },
{ element: "C", location: [ 1.391783, 0.076397, -0.012244 ] },
{ element: "C", location: [ 0.762101, -1.168506, 0.026080 ] },
{ element: "C", location: [ -0.631044, -1.242903, -0.011791 ] },
{ element: "C", location: [ -1.391806, -0.076430, -0.014083 ] },
bonds: [
{ atoms: [ 0, 1 ], order: 2 },
{ atoms: [ 1, 2 ], order: 1 },
{ atoms: [ 2, 3 ], order: 2 },
{ atoms: [ 3, 4 ], order: 1 },
{ atoms: [ 4, 5 ], order: 2 },
{ atoms: [ 0, 5 ], order: 1 }

If you want to make properly formatted JSON, you can use either `` as a script or run your own imolecule server to convert most chemical file formats to JSON.

Open Babel

[Open Babel]( is an open-source library
for interconverting over 100 chemical file formats. imolecule uses Open Babel
to convert input formats to JSON before drawing. Therefore, to use imolecule
with non-JSON formats, you will need Open Babel.

Open Babel is best installed from source. For more, read through the
[Open Babel installation instructions](

git clone
mkdir build && cd build
cmake ../openbabel -DPYTHON_BINDINGS=ON
make && make install

Older versions of open babel can be found through standard package managers,
and do support most of the functionality of the development version. If you
are struggling with building from source, check your package manager for

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
imolecule-0.1.13-py2.py3-none-any.whl (475.4 kB) Copy SHA256 hash SHA256 Wheel 3.4
imolecule-0.1.13.tar.gz (354.4 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page