Reference   |   Registration/Download   |   Guide/Tutorial   |   FAQ   |   Required Programs   |   Release Notes  

HKL2MAP is a graphical user-interface for macromolecular phasing. Running as a Tcl/Tk client, it is platform-independent, and in combination with the SHELX software it can be used on Linux as well as MacOS X platforms.

The current version (0.4.e as of June 2017) connects several programs from the SHELX-suite to guide the user from analysing scaled diffraction data (SHELXC), via substructure solution (SHELXD) and phasing (SHELXE) to displaying an electron density map (Coot). HKL2MAP now supports "live" display of SHELXE auto-tracing models while the iterative auto-tracing/density modification process is running.

To use HKL2MAP, you need to have licenced versions of SHELXC/D/E and Coot in the executable path of your computer.


If you use HKL2MAP in you work, please cite the following publication:

Thomas Pape & Thomas R. Schneider
HKL2MAP: a graphical user interface for phasing with SHELX programs
J. Appl. Cryst. 37:843-844 (2004).

User Guide and Tutorial

A current tutorial can be found here (PDF, 1.48 MBytes)

Older items:


What can I do if HKL2MAP does not work?

  • please check that the script was properly detached from the email. The first line should read: '#!/usr/bin/wish' or '#!/usr/bin/env wish', and the last line should be: 'focus .project.entry'
  • please check that you have Tcl/Tk with a version number equal or greater than 8.3: from the UNIX-command line:
    UNIX> /usr/bin/wish
    % puts $tk_version

  • If you get an error message along the lines of ': Bad interpreter', your mail-program may have added or removed something when saving the attachment. Please check the HKL2MAP-script by using the unix-command wc. For hkl2map-0.4.e-beta-dist, wc should give the following result:
    > wc hkl2map-0.4.e-beta-dist
    5726 32115 212908

    You may get away by deleting the last character of each line by the following unix-command:
    > sed 's/.$//g' hkl2map-0.4.e-beta-dist > hkl2map
    On some systems, you may also find a utility program called dos2unix or to repair the changes made by the mail program (thanks to Bradley Ford for pointing this option)

Why does HKL2MAP still refuse to work on my machine (MacOS vs. Linux)?

  • When you followed the README instructions (hkl2map-0.4.e-beta-read) of the downloaded tarball, you made the script executable.
    However, Linux and MacOS X require different top lines to access the Wish (Tcl/Tk) interpreter. Thus simply open the HKL2MAP file with a text editor, check whether the top line contains the MacOS line:
    #!/usr/bin/env wish
    or the Linux line:
    and swap the uppermost lines, in case that the configuration does not fit your platform.

Is it possible to reconstruct the graphs made by HKL2MAP from a previous run?

  • Yes, select: Tools/SHELXC[D,E]-graphics from the main menu of the HKL2MAP window. In the file browser, select the log file corresponding to the graph that you want to reconstruct.

Where can I download a fresh version of Tcl/Tk?

  • On most Linux distributions, as well as on MacOS X, Tcl and Tk come preinstalled.
  • A good place to look for the latest versions (in case that you have to or wish to upgrade) is: . The download section provides precompiled packages for Linux & MacOS X (plus Windows).

Required and Related Programs


  • The SHELX-programs used by HKL2MAP, shelxc, shelxd, and shelxe are available for both Linux and MacOS X from the SHELX-site
  • Paul Emsley's coot, as required for graphical map/model display, is included to the recent versions of CCP4 (since release 6.5.0).
    • Stand-alone executables for Linux are available on P. Emsley's home page
    • Stand-alone executables for the latest MacOS X versions are generally provided by the Scott lab @ UCSC and available on a dedicated web page.


  • A program mtz2sca (written by Tim Gruene) to convert mtz-files to something that can be used by HKL2MAP is available at: Tim Gruene's page and it is part of CCP4 since release 6.4.0
  • A shell-script to convert phs-files containing phased reflections to mtz-format is available: phs2mtz.

Release Notes

Version 0.4 - Jul 2015

  • Display of "real time" freely rotatable ribbon graphs for SHELXE auto-tracing models
  • Several minor bug fixes.

Version 0.3 - Mar 2013

  • multi-processor version of SHELXD
  • auto-tracing in SHELXE
  • free-lunch data extension in SHELXE
  • Coot as graphical display


For any problems/comments/suggestions please contact the hkl2map service mail.

Last Update: 01/February/2016

Pages on this server were created by Thomas R. Schneider (thomas.schneider at and Fabio Dall'Antonia (fabio.dallantonia at FD and TRS accept full responsibility for the content of these pages, for which EMBL is not responsible by any means.