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.

      • Apple XCode: Before attempting to install any of the third-party compiler suites below, you will need to install the Apple XCode Command Line Tools (CLT) and make sure that they are up-to-date with your OS:
          xcode-select --install
        Having out-of-date CLT can result in malfunctioning Homebrew or MacPorts compilers.
      • 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@11 package:

              $ brew install gcc
           In C-shell variants (tcsh/csh):           In Bourne shell variants (bash/sh/zsh):
              $ setenv CC /usr/local/bin/gcc-11         $ export CC=/usr/local/bin/gcc-11
              $ setenv CXX /usr/local/bin/g++-11        $ export CXX=/usr/local/bin/g++-11
              $ setenv FC /usr/local/bin/gfortran-11    $ export FC=/usr/local/bin/gfortran-11
          NOTE: For the M1/ARM architecture, you must use the Rosetta2 Intel binary translation to install your Homebrew compilers for use with HEASoft, as follows:

          1) Make sure Rosetta is installed:

            $ sudo softwareupdate --install-rosetta
          2) Install XQuartz version 2.8.1 or newer.

          3) Install Homebrew, prefacing their install commands with the Rosetta Intel prefix "arch -x86_64", for example:

            $ arch -x86_64 /bin/bash -c "$(curl -fsSL"
            $ curl -fsSL >
            $ chmod +x ./
            $ arch -x86_64 ./
          4) Install the Homebrew packages gcc, perl and python using the same Rosetta Intel prefix. Use of the Rosetta prefix should install Homebrew in /usr/local rather than the default Homebrew location for Apple Silicon of /opt/homebrew:
            $ arch -x86_64 /usr/local/bin/brew install gcc
            $ arch -x86_64 /usr/local/bin/brew install perl
            $ arch -x86_64 /usr/local/bin/brew install python
          5) Set the compiler variables as above.
           In C-shell variants (tcsh/csh):           In Bourne shell variants (bash/sh/zsh):
            $ setenv CC /usr/local/bin/gcc-11         $ export CC=/usr/local/bin/gcc-11
            $ setenv CXX /usr/local/bin/g++-11        $ export CXX=/usr/local/bin/g++-11
            $ setenv FC /usr/local/bin/gfortran-11    $ export FC=/usr/local/bin/gfortran-11
            $ setenv PERL /usr/local/bin/perl         $ export PERL=/usr/local/bin/perl
            $ setenv PYTHON /usr/local/bin/python3    $ export PYTHON=/usr/local/bin/python3
          As noted below, M1 users are also advised to put /usr/bin ahead of other paths (especially e.g. those used by Anaconda, etc.) in their PATH in order to avoid potential architectural errors with libcurl, etc.:
              $ setenv PATH "/usr/bin:$PATH"            $ export PATH="/usr/bin:$PATH"
        • MacPorts
        • Use for example the entire gcc11 package:

              $ sudo port install gcc11 perl5
           In C-shell variants (tcsh/csh):           In Bourne shell variants (bash/sh/zsh):
              $ setenv CC /opt/local/bin/gcc-mp-11       $ export CC=/opt/local/bin/gcc-mp-11
              $ setenv CXX /opt/local/bin/g++-mp-11      $ export CXX=/opt/local/bin/g++-mp-11
              $ setenv FC /opt/local/bin/gfortran-mp-11  $ export FC=/opt/local/bin/gfortran-mp-11
              $ setenv PERL /opt/local/bin/perl          $ export PERL=/opt/local/bin/perl
          Please note that MacPorts compiler libraries are (or may soon be) installed using an rpath location rather than a hard-coded directory path, so when using MacPorts compilers we recommend that - prior to configuring heasoft - you set the LDFLAGS environment variable to tell heasoft executables where to find these libraries at runtime, for example:
              $ setenv LDFLAGS "-Wl,-rpath,/opt/local/lib/gcc11"   $ export LDFLAGS="-Wl,-rpath,/opt/local/lib/gcc11"
          Note that the path may differ depending on your MacPorts installation and the compiler version, but the directory you use should contain for example "libgfortran.5.dylib" and "libgcc_s.1.1.dylib".

          Lastly, if you use MacPorts, please refer to the MacPorts Migration page when updating your OS to avoid portability issues.

          NOTE: For the M1/ARM architecture: as discussed for the Homebrew compilers above, you will need to install your MacPorts compilers using the Rosetta2 Intel binary translation. This approach for MacPorts has not been widely tested at the HEASARC, but further guidance may be forthcoming.

        • 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.). However, on newer macOS we have found that using the Apple Perl (/usr/bin/perl) alongside third-party GCC (Homebrew, MacPorts, etc.) may cause build problems as a result of flags that the Apple Perl inserts into our C/Perl library configuration. So, we recommend that you install e.g. the Homebrew or MacPorts Perl to match your third-party compilers.

      • 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 - as described above - 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-11    $ export FC=/usr/local/bin/gfortran-11
          $ setenv CC /usr/local/bin/gcc-11         $ export CC=/usr/local/bin/gcc-11
          $ setenv CXX /usr/local/bin/g++-11        $ export CXX=/usr/local/bin/g++-11
          $ setenv PERL /usr/local/bin/perl         $ export PERL=/usr/local/bin/perl
          $ setenv PYTHON /usr/bin/python           $ export PYTHON=/usr/bin/python
      Users are also advised to put /usr/bin ahead of other paths (such as those used by MacPorts, Anaconda, etc.) in their PATH in order to avoid potential errors.
          $ 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
      Alternatively, users may alter their session to cancel any Anaconda or other package initialization by editing their profile or other shell resource files.

      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.30/BUILD_DIR/              $ cd heasoft-6.30/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.30:
          $ cd ~
          $ tar zxf Downloads/heasoft-6.30src.tar.gz
          $ cd heasoft-6.30/BUILD_DIR/
          $ ./configure --prefix=/usr/local/heasoft-6.30
          $ 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.30/(PLATFORM)
          source $HEADAS/headas-init.csh
         For users of Bourne Shell (sh, ash, ksh, bash, zsh):
          export HEADAS=/path/to/your/installed/heasoft-6.30/(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: Thursday, 21-Apr-2022 09:25:16 EDT