ISOLDE: Bringing structural biology to life


Frequently asked questions

What do I need to run it?

The short answer: ideally, a single modern workstation with the best GPU you can afford. However, ISOLDE is still usable even on a MacBook Air. ISOLDE is distributed for Windows, MacOS and Linux (built in CentOS 7 using GCC 4.9).

The longer answer: molecular dynamics (MD) is a computationally extremely demanding task. The MD engine underlying ISOLDE (OpenMM) relies heavily on GPU-accelerated computing to achieve usable speed in a workstation environment. The better your GPU, the better your experience in ISOLDE will be. Using the demo model bundled with ISOLDE (a 229-residue protein model with a 3 Angstrom resolution X-ray map) with live map recalculation turned off, my desktop Xeon workstation equipped with a Nvidia Titan Xp achieves just under 20 coordinate updates (1000 simulation steps) per second while maintaining a graphics framerate of 30-40 frames per second. My "power" laptop (a gaming model with an Intel Core i7 CPU and an Nvidia GTX1070 GPU) gives essentially indistinguishable performance for the same model. At the other end of the scale, my MacBook Air will run this model (and larger models running into the thousands of residues) - but only at a rate of 2-3 coordinate updates per second. Note, however, that you rarely need to simulate the whole model at once in ISOLDE - just a small buffer region around the site you wish to fix - so it is still very possible to do useful work on such a machine.

Oh - and you'll also want to be working with a real mouse. Trackpad support is a work in progress.

How do I get it?

ISOLDE is distributed as a plugin to UCSF ChimeraX 0.9, and can be easily installed via its built-in Tool Shed. See here.

(Important Note: ISOLDE 1.0b3 requires the ChimeraX 0.9 release version, and will not work with newer daily builds)

Starting with ISOLDE 1.0b3, expect regular development builds to start appearing on the Tool Shed. These will be built to work with the latest daily builds of ChimeraX, and at this stage there is no guarantee of backward compatibility.

How do I use it?

ISOLDE comes bundled with comprehensive documentation of its GUI and (for the adventurous) its Python API. This is also provided .



I'm having installation or running issues. Help?

In Linux, ChimeraX crashes when I load a model in ISOLDE

For Linux, ISOLDE is compiled against the RedHat rpm build of ChimeraX using gcc 4.9, to be as close as possible to a lowest common denominator for modern Linux operating systems. Unfortunately, the ChimeraX releases for Ubuntu are built with much newer GCC versions and are not compatible with ISOLDE. If you're using Ubuntu, you'll need to work with the "Generic Linux 64-bit" build of ChimeraX.

I installed ChimeraX 0.9/ISOLDE 1.0b3 and get a ModuleNotFoundError when loading a model

In ChimeraX 0.9 there is a bug in the Tool Shed causing it to ignore the ChimeraX version requirement when installing a package as a dependency of another. This is causing the latest development build of Clipper (built for the ChimeraX 0.91 daily builds) to be installed. Due to API changes in ChimeraX this is not backward-compatible with ChimeraX 0.9. To correct the issue you have two options:

1. (Recommended) Download and install the latest ChimeraX daily build, and install ISOLDE into that. This will give you the latest ISOLDE and Clipper dev builds.

2. Downgrade Clipper to the correct version. Go to Tools/More Tools..., find and click the link for Clipper, click the "Release History" tab, then scroll down until you find the link to 0.9.4 for your operating system. Click the link to install, then restart ChimeraX when done.


The below bugs affected the ChimeraX 0.8 / ISOLDE 1.0b2 release, and are fixed in ChimeraX 0.9 / ISOLDE 1.0b3. Please contact me if you encounter any further trouble.

I get a UnicodeDecodeError on attempting to install ISOLDE

This is an unfortunate bug in the 0.8 release of ChimeraX, and will require you to make a minor edit to fix. You'll need to open the following file in a text editor:

Windows: C:\Program Files\ChimeraX\bin\Lib\site-packages\chimerax\core\toolshed\

MacOS: /Applications/

Linux rpm or .deb: /opt/UCSF/ChimeraX/lib/python3.6/site-packages/chimerax/core/toolshed/

Linux tarball: replace /opt/UCSF/ChimeraX with the directory you untarred to.

On lines 863, 864 and 873, replace:



.decode("utf-8", "backslashreplace")

... then restart ChimeraX, and your ISOLDE installation should now run successfully.

I see a KeyError: "ChimeraX_Clipper" on starting ChimeraX

This is another minor bug which crept into the ChimeraX 0.8 release, and will require you to clear the ChimeraX cache. To do so, first find the cache directory by running the following on the ChimeraX command line (directly under the OpenGL window):

info path user versioned cache

The cache directory will be reported in the ChimeraX log window. Navigate to and delete this directory in your operating system's file browser, and the error should go away.

I want to install ISOLDE for all users, but get a "Permission Denied" EnvironmentError

In order to install for everyone, you will need to be running ChimeraX under a root / Administrator account.

If you're in Linux, before running sudo ChimeraX you will need to change line 120 of /path/to/chimerax/lib/python3.6/site-packages/ from:

    opts.get_available_bundles = True


    opts.get_available_bundles = False

Don't forget to change it back when you're done.

In Linux, I get an OSError: undefined symbol when starting ISOLDE

If, on starting ISOLDE, you see an error containing a line similar to:

OSError: /home/myuser/.local/share/ChimeraX/0.8/site-
packages/chimerax/isolde/ undefined symbol:

... this is a somewhat odd bug wherein for some systems, running the ChimeraX executable from a symbolic link causes the Tool Shed to fail to find the main ChimeraX library directory. To work around it, find the true ChimeraX executable:

ls -l `which chimerax`

... and run that instead. For convenience, you may want to wrap this in a simple Bash script on your path:

/path/to/chimerax/bin/ChimeraX $@


ISOLDE is developed and maintained by Tristan Croll in the lab of Randy Read at the Cambridge Institute for Medical Research and supported by Prof. Read's Wellcome Trust Principal Research Fellowship 209407/Z/17/Z. Development and testing has been aided by the generous donation of a GTX Titan Xp GPU by NVIDIA Corporation.

Website design by Tristan Croll based on Hielo by Templated under a CC BY 3.0 license. Powered by Django-CMS.