Getting started

Learn how to use the computational crystallography toolbox, the open source library for crystallography and cryo-EM.


Go to the Download page to get the most recent cctbx source code as binary installer for Linux, MacOS and Windows.


Installation is very simple and fast. After uncompressing the bundle, run the install --prefix= command to install on macOS and Linux. On Windows, uncompressing the zip file will provide a working copy of cctbx.

Running on the command line

Type this into a terminal window to start python from cctbx so that it knows about all the cctbx modules:


The libtbx.python command runs a version of python that already knows about the cctbx so you can easily import cctbx functions. For example:

from iotbx.data_manager import DataManager    # Load in the DataManager

Running as a script

Sometimes you want to save the commands in a script. This avoids typing the same text over and over again if you want to perform some actions on many files. For example, save the following lines in a file, you can call it (this page explains in more detail what the script does).

from iotbx.map_model_manager import map_model_manager      # load in the map_model_manager
mmm=map_model_manager()          # get an initialized instance of the map_model_manager
mmm.generate_map()               # get a model from a small library model and calculate a map for it
mmm.write_map("map.mrc")         # write out a map in ccp4/mrc format
mmm.write_model("model.pdb")     # write out a model in PDB format

Then run the script by typing the following command in a terminal:


You just ran your first cctbx script which produced example map and model files.

Setting up a Jupyter Notebook

Coming soon...

I am completely new to cctbx. Where do I start?

If you want to use the cctbx, you most likely want to do some actions on models, crystallographic data files or cryo-EM maps. The following pages give an introduction to higher level objects and methods for this purpose.

High-level cctbx objects
Overview of high level objects that represent things like data, models, restraints, etc. Learn how to create your first object, the map_model_manager..
Reading and writing files

Most scripts will act on files, so this section should be of interest to everyone. Use the DataManager to conveniently read and write data and model files.

The cctbx model manager

The model manager lets you do operations on models. Learn how to to set up the model manager, apply coordinate shifts, do atom selections and calculate model-based map coefficients.

The cctbx map manager

The map manager lets you do operations on maps. Learn how to read and save maps, change a map, convert a real-space map to a Fourier representation and back and manipulate maps that represent only a part of a full map. The tutorial also explains how to find and represent map reconstruction symmetry.

The map-model manager

The map-model manager is useful to keep track of both maps and models. This tutorial shows how to set up the manager, how to cut out a piece of a map around a part of a model and how to create masks.

I got the basics. How can I learn more?

Coming soon...

Community and help

Asking for help

  • If you want to ask a question to developers and users, subscribe to the cctbx mailing list. Here are the archives of the cctbxbb.
  • You can also write to the Phenix/cctbx developers directly:


Want to contribute to the cctbx? Here is the GitHub page.