How to build CCP4

This instruction is for building both CCP4 releases and the latest development snapshots.

If you just want to use the CCP4 suite, look for binaries instead.

Source tarballs include content previosly (up to ver. 6.3.0) distributed in ccp4-*-core-src.tar.gz, ccp4-*-phaser-cctbx-src.tar.gz, tcltk++_*.tar.gz, and more.


Subdirectories of the checkout directory are either checkouts of source code repositories or (for third-party software) unpacked tarballs. Each module has own build system (apart from the modules that are simply copied). It is possible to build all modules/subdirectories manually, one by one, typically with 2-3 commands for each module (e.g. configure [args]; make install or cmake [args]; make install), but to make things easier we provide a thin layer of scripts that does this automatically.

Like with almost any software, the installation from sources copies all files useful to the user to selected location. By default this location is ccp4-VERSION subdirectory, not /usr/local.

The bundle includes a simple auto-updating mechanism (which uses Bazaar underneath).


You need compilers and other tools, and a number of 3rd-party libraries. For your convenience many libraries are included, but you may choose to use versions from your system instead.

Platform-specific details are in the next sections.

What you must have

C, C++ and Fortan compilers, make and m4 programs are required.

Building graphical programs requires fontconfig, X11 (+ Xrender, Xinerama, Xt, Xaw) and OpenGL libraries, all with header files.

wget or curl is needed to automatically download Qt, Coot, and from time to time for updates. git and patch are needed for some updates.

The build system requires Python 2.6 or 2.7. If the default Python on your system is older, or if it is Python3, change the first line of checkout/devtools/cj. Make sure that setuptools (needed by suds, lxml, etc.) are installed for your Python.

What can be bootstrapped

Qt 4.8 can be automatically downloaded and built from sources, but usually it is faster to install binaries for your OS.

SWIG 2.0.5+ is needed to build ccp4MG.

Included 3rd-party software

Built if explicitely requsted (details below):

  • Python 2.7 (some Python programs work only with ver. 2.7)
  • setuptools (build it if you've build Python)
  • CMake (ver. 3.1+ is needed for building)
  • bzr (for updating sources from CCP4 repositories)

Built by default (opt-out by editing cj.rc):

  • Boost libraries
  • Tcl/Tk 8.4 (for ccp4i and imosflm, 8.5+ may not work)
  • zlib (for many programs)
  • libxml2 (for rapper and coot)
  • libxslt (for lxml)
  • libjpeg (for diff-image and libgd)
  • libpng (for libgd)
  • libgd (for Raster3d and PLplot)
  • PLplot (for chooch)
  • GSL (for chooch, theseus, coot)
  • LAPACK (for refmac, scala, crank)
  • FFTW2 (for clipper)
  • numpy, lxml (for ccp4MG)
  • patchelf (Linux only, it is used to change RPATHs after build)
  • and many more.

On Linux

Install prerequisites using system package manager.


apt-get install bzr make cmake wget g++ gfortran m4 patch \
          libqt4-dev libqtwebkit-dev python-dev default-jdk libxml2-dev \
          libxt-dev libfontconfig1-dev libxrender-dev libxinerama-dev \
          libxaw7-dev swig


yum install bzr make cmake wget gcc-c++ gcc-gfortran m4 patch \
          qt-devel qtwebkit-devel python-devel java-devel libxml2-devel \
          fontconfig-devel libXt-devel libXrender-devel libXinerama-devel \
          libXaw-devel swig
# and if you want to build coot:
yum install xz intltool mesa-libGLU-devel libXmu-devel


zypper install bzr make cmake wget gcc-c++ gcc-fortran m4 patch \
          qt-devel libQtWebKit-devel python-devel java-devel libxml2-devel \
          libXaw-devel swig

If you want to build Qt4 yourself, make sure you have installed package that provides gstreamer-app-0.10.pc.

If you use Qt4 or CMake from your system, it's better to also use system version of zlib and libxml2 (Qt4 and CMake are often linked to libxml2). Just add this line to cj.rc:

skip = ['zlib', 'libxml2']


Official CCP4 binaries for OS X are built with Intel Compiler. GCC and Clang + GFortran also work and are tested.

Install bzr, CMake, and Qt4.8.

Installation is easier if you use MacPorts:

port install cmake qt4-mac swig-python gcc5 bzr

or Homebrew:

brew install cmake qt4 swig gcc bzr  # it tells you to adjust PYTHONPATH

To use compilers with non-default names edit cj.rc or do:

export CC=gcc-5 CXX=g++-5 FC=gfortran-5  # it is example only

Make sure you have X11 (XQuartz) installed. It was included in OSX up to v10.7.

Libraries included in OSX 10.6+ (zlib, libxml2, sqlite3, etc). are skipped by default. To skip other libraries that are installed locally, for example Boost, add to cj.rc:

skip += ['boost']


The latest Boost version at this moment (1.55) does not compile with the latest Apple compiler. MacPorts/Homebrew have patches for this problem so it's easier to install it using package manager and add it to the skip list.

On Windows

Description how to set up build environment on Windows has not been kept up to date and is left out for now. If you need to build CCP4 on Windows contact us.


It is possible to build any subset of CCP4 (the build system takes care of dependencies) but for simplicity we describe here how to build the complete CCP4 suite.

Change directory into unpacked sources.

If you don't have patchelf installed, build it from source:

./build patchelf

Install Qt4.8, including QtWebKit, in a usual way for your OS. Make sure that qmake (or qmake-qt4) is in the PATH. Alternatively, our build scripts can try to download and compile Qt4 from source:

./update qt4; ./build qt4

If you don't have CMake 3.1+ installed, build it from source:

./build cmake

If you don't have Python 2.7 installed, build it from source:

./build python setuptools

If you don't have SWIG 2.0.5+ installed, build it from source:

./update swig; ./build swig

Build CCP4 with one of these commands:

./build ccp4-osx
./build ccp4-linux
./build ccp4-windows  # (in Windows MinGW/MSYS shell)

Building can be customized by editing the cj.rc file or setting environmental variables. For example:

CC=gcc-5 CXX=g++-5 FC=gfortran-5 ./build ccp4-linux

uses specified compilers.

Other useful variables are CFLAGS, CXXFLAGS and FFLAGS (options for C, C++ and Fortran compiler), LDFLAGS (options for linker), TARGET (for cross-compiling), BUILD_STATIC (set to 1 to build static libraries), STATIC (similar, experimental). See comments in the cj.rc file for details.

After building on Mac it may be necessary to run install_name_tool to set locations of libraries. We have a script devtools/misc/ that does this automatically, setting relative paths to libraries so the whole bundle works even when moved to a different directory.

Advanced usage

If you have a look at the build and update scripts, you will see they call checkout/devtools/cj. The cj script has more subcommands. You may use it directly. For example, to uninstall boost do:

checkout/devtools/cj uninstall boost


/my/python2 checkout/devtools/cj uninstall boost

Some of the subcommands take options. In particular, ./build (and cj build) can be called with options --force and --clean to, respectively, build the module regardless if it has changed, and run make clean before building.


The build command installed everything in the ccp4-6.5 subdirectory. Before you use it, make sure that older CCP4 is not used ($CCP4, etc. are not set) and run the BINARY.setup script:


Then source one of the two setup files (they are created by BINARY.setup):

. ccp4-6.5/bin/ccp4.setup-sh        # in bash, dash, zsh
source ccp4-6.5/bin/ccp4.setup-csh  # in csh, tcsh

You can move the ccp4-6.5 directory where you like, just re-run BINARY.setup. And (for the sake of updates) link new location from the original location.


First install bzr (Bazaar). Either use your favourite package manager or build it from sources:

./build bzr

Download updates:


and rebuild and install changes:

./build ccp4-linux

Local changes

Each module (checkout/<module>) can be built separately. After modifying, say, ccp4-progs you can rebuild and reinstall only this module:

./build only ccp4-progs

To see local changes, go to the changed module and type:

bzr diff

To revert local changes do:

bzr revert

Note: Default configuration uses anonymous lightweight (no history) checkout. If you have developer access and want to commit the changes back, the easiest way is to first check out your module via ssh (You could use bzr reconfigure command if it wasn't buggy):

cd checkout
rm -r MODULE
bzr checkout bzr+ssh:// MODULE


On Linux and OS X you can also build coot with its 40+ prerequisites (requires xz and intltool):

./build coot

The prerequisites include GTK+ and glib. On Linux Qt4 may be linked with glib, so if you use system Qt4 use also system glib to avoid conflicts (install glib headers and add skip+=['glib'] to cj.rc).

Known problems

Other problems?

Do not hesistate to contact CCP4, we need feedback. Email helpdesk:, or me directly: