Getting started

A quick overview of how to get started with Phenix.

1. Download Phenix and install

Download information and installation instructions for each platform can be found here.

2. The Phenix GUI

The Phenix GUI serves as a frontend to the command-line programs, with the addition of several graphical utilities. The GUI runs on Linux, MacOS and Windows (Windows has some limitations).
The main GUI is started by typing the command phenix; the GUI will also open automatically when you launch any of the individual program GUIs. You should not run more than one instance of the GUI at a time, to avoid conflicts with internal database files.


Individual programs are grouped by category (see screenshot). Most of these correspond to command-line programs, and the documentation for the command-line version should be the primary reference for understanding program behavior and inputs. However, additional GUI documentation is available for some programs.

Other tools

A number of simpler tasks involving file modification and visualization can be accessed by clicking the button labeled "Other tools" on the toolbar.

3. Projects

Phenix manages data and job history by grouping them into projects. You will be prompted to create a project the first time you start the GUI. On subsequent launches, Phenix will attempt to guess the project based on the current directory. Project management requires the following:

  • Project directories may not be nested, i.e. you may not create a project for a directory that is part of an existing project, or that has a subdirectory that is owned by another project.
  • When a project is created Phenix will create a folder ".phenix" in the project directory; this is used to store job history, temporary files, and other internal data. Users should not need to modify this folder. All functions related to project management are available from the main GUI.
One important function of the projects is storing job history; the history saves basic statistics and configuration files, and can restore the parameters and results of any successful previous run.

4. Running Phenix Tutorials

A number of examples using published models and data are included in the Phenix installation; they can be automatically loaded into the GUI as new projects. To load tutorial data, click on "New project" in the main GUI; this window also appears the first time the Phenix GUI is started (before any projects have been created). The button "Set up tutorial data" will open a new dialog with a list of examples, grouped by the methods they are intended to demonstrate.
The example data are often used for live demonstrations at workshops (in-person or virtual).

5. Preferences

Some of the behavior of the GUI can be customized via the Preferences dialog, which is available from the File menu ( Linux) or Phenix menu (Mac) and on the toolbar of most programs.
Other Preferences settings determine what external programs are used for various file types, interactions with molecular graphics programs (Coot, PyMOL, and the simple built-in graphics), and options for some of the specific modules in Phenix.

6. Reporting bugs

Bugs in the code may result in a pop-up window containing a detailed error message. Clicking "OK" will send an email to the Phenix developers with this information. We strongly encourage users to submit these reports, as they are one of the primary mechanisms by which we identify coding errors. The report will include the error message, information about the host system, and user name/email, but not any other data. The email address is important for contacting users with advice on how to work around any issues or for requesting more information or data required to track down and fix a bug. We appreciate the help in making Phenix more robust.