Installing HEASoft - Mac OS

Instructions for Source Code or Pre-Compiled Binary distributions

    • Installations from the source code are generally recommended over the pre-compiled binaries to avoid any potential portability issues. Note also that source code builds are required for users who wish to load local models in Xspec or use the Xspec Python interface (PyXspec).

      The instructions below assume that you have already acquired a HEASoft tar file and have unpacked it (using e.g. "tar zxf [tar file]") on your machine.

    • Prerequisite packages:

      In order to build HEASoft from the source code distribution, you will need some additional software:

      • X11: We recommend XQuartz but X11 is also available via the various Mac package managers.

      • Compilers: In the past we have typically suggested pairing the Apple XCode C compilers with a third-party Fortran, but are now recommending that you use a complete set of third-party compilers, i.e. C, C++, and Fortran. Multiple options are available via Mac package managers such as those listed below.

        • Homebrew
        • Use for example the entire gcc@10 package, but note that on Intel Big Sur you should be sure to use one of the latest versions (10.2.0_3 or newer) to avoid run-time problems in xspec. For building HEASoft with Homebrew compilers under ARM64 Big Sur, please visit our known issues page for a patch and step-by-step guide.

              $ brew install gcc
           In C-shell variants (tcsh/csh):           In Bourne shell variants (bash/sh/zsh):
              $ setenv CC /usr/local/bin/gcc-10         $ export CC=/usr/local/bin/gcc-10
              $ setenv CXX /usr/local/bin/g++-10        $ export CXX=/usr/local/bin/g++-10
              $ setenv FC /usr/local/bin/gfortran-10    $ export FC=/usr/local/bin/gfortran-10
        • MacPorts
        • Use for example the entire gcc10 package:

              $ sudo port install gcc10
           In C-shell variants (tcsh/csh):           In Bourne shell variants (bash/sh/zsh):
              $ setenv CC /opt/local/bin/gcc-mp-10       $ export CC=/opt/local/bin/gcc-mp-10
              $ setenv CXX /opt/local/bin/g++-mp-10      $ export CXX=/opt/local/bin/g++-mp-10
              $ setenv FC /opt/local/bin/gfortran-mp-10  $ export FC=/opt/local/bin/gfortran-mp-10
          If you use MacPorts, please refer to the MacPorts Migration page when updating your OS to avoid portability issues.

        • HPC For Mac OS
        • These tar files unpack in /usr/local:

           In C-shell variants (tcsh/csh):           In Bourne shell variants (bash/sh/zsh):
              $ setenv CC /usr/local/bin/gcc            $ export CC=/usr/local/bin/gcc
              $ setenv CXX /usr/local/bin/g++           $ export CXX=/usr/local/bin/g++
              $ setenv FC /usr/local/bin/gfortran       $ export FC=/usr/local/bin/gfortran

          Please note that on macOS Catalina (and newer) these compilers are not currently supported for building HEASoft due to the additional include and library path requirements noted on the HPC page.

        • Fink

      • Perl: A Perl interpreter is needed for many HEASoft tasks, and any modern version should be fine (Apple XCode, Homebrew, MacPorts, etc.).

      • Python: Python is only required if you plan to use PyXspec or the Python interface to the HEASP library. Any modern Python (version 2 or 3) should be suitable (Apple XCode, Homebrew, MacPorts, Anaconda, etc.).

    • Building the software:

      After installing the prerequisite packages above, most users should just follow the basic GNU-like build procedure outlined in the HEASoft installation guide, i.e.:

      First, make sure that the configure script will choose the correct set of compatible compilers for the build, for example:
       In C-shell variants (tcsh/csh):           In Bourne shell variants (bash/sh/zsh):
          $ setenv FC /usr/local/bin/gfortran-9     $ export FC=/usr/local/bin/gfortran-9
          $ setenv CC /usr/local/bin/gcc-9          $ export CC=/usr/local/bin/gcc-9
          $ setenv CXX /usr/local/bin/g++-9         $ export CXX=/usr/local/bin/g++-9
          $ setenv PERL /usr/bin/perl               $ export PERL=/usr/bin/perl
          $ setenv PYTHON /usr/bin/python           $ export PYTHON=/usr/bin/python
      Users are also advised to put /usr/bin ahead of /opt/local/bin in their PATH in order to avoid picking up a MacPorts assembler (as) that may cause configure errors ("I don't understand 'm' flag!"):
          $ setenv PATH "/usr/bin:$PATH"            $ export PATH="/usr/bin:$PATH"
      External packages (e.g. Anaconda) may set compiler flags in the environment which can break a HEASoft build, so users are advised to unset all "FLAGS" variables:
          $ unsetenv *FLAGS                         $ unset CFLAGS CXXFLAGS FFLAGS LDFLAGS
      Other software packages (e.g. XMM-SAS) may change your LD_LIBRARY_PATH (or DYLD_LIBRARY_PATH on Macs) environment variable, and this can break a HEASoft build, so users are advised to check their [DY]LD_LIBRARY_PATH variable and remove any paths that aren't necessary. Typically none should be needed and this variable can remain empty when building HEASoft unless you are using a custom compiler suite for the build.

      Next, configure and build the software. Note that you should commit to the location of the software prior to running the configure script. Once you have built the software, library paths are hard-coded into the executables, and they will not function correctly if relocated.
          $ cd heasoft-6.28/BUILD_DIR/              $ cd heasoft-6.28/BUILD_DIR/
          $ ./configure >& config.txt               $ ./configure > config.txt 2>&1
          $ make >& build.log                       $ make > build.log 2>&1
          $ make install >& install.log             $ make install > install.log 2>&1
      Note that you should let each step finish before proceeding to the next. The installation guide contains descriptions of optional configuration flags that more advanced users may wish to utilize.

    • Lastly, please also note that the compiler settings described above will NOT pass to a sudo shell, so if you want to install HEASoft in a location which requires su write privileges, we recommend that you configure and build the software in a location writeable by you, and only when doing the final install step should you use sudo. Here is an example in which a user has acquired the source code tar file and it is sitting in their Downloads/ directory; they then unpack, configure and build the HEASoft source code in their home directory and then install under /usr/local/heasoft-6.28:
          $ cd ~
          $ tar zxf Downloads/heasoft-6.28src.tar.gz
          $ cd heasoft-6.28/BUILD_DIR/
          $ ./configure --prefix=/usr/local/heasoft-6.28
          $ make
          $ sudo make install

    • Initialization:

      To initialize the software, do the following:
         For users of C Shell variants (csh, tcsh):
          setenv HEADAS /path/to/your/installed/heasoft-6.28/(PLATFORM)
          source $HEADAS/headas-init.csh
         For users of Bourne Shell (sh, ash, ksh, bash, zsh):
          export HEADAS=/path/to/your/installed/heasoft-6.28/(PLATFORM)
          . $HEADAS/
      In the examples above, (PLATFORM) is a placeholder for the platform- specific string denoting your machine's architecture, for example:



    If FTOOLS has been useful in your research, please reference this site ( and use the ASCL reference for HEASoft [ascl:1408.004] or the ASCL reference for the original FTOOLs paper [ascl:9912.002]:

    Blackburn, J. K. 1995, in ASP Conf. Ser., Vol. 77, Astronomical Data Analysis Software and Systems IV, ed. R. A. Shaw, H. E. Payne, and J. J. E. Hayes (San Francisco: ASP), 367.

    Web page maintained by: Bryan K. Irby

    HEASARC Home | Observatories | Archive | Calibration | Software | Tools | Students/Teachers/Public

    Last modified: Monday, 22-Feb-2021 14:05:13 EST