Installing HEASoft on a Mac

This page includes instructions for installing Source Code or Pre-Compiled Binary distributions.

See also the video walkthrough describing the installation process.

A. SOURCE CODE INSTALLATION

We have historically recommended installations from the source code over the pre-compiled binaries due to portability issues, but are now offerring pre-compiled installations via the conda (or mamba) package manager. Please see our conda page for more information.

Installations from the source code distribution (or conda) are required for users who wish to load local models in Xspec or use the Xspec Python interface (PyXspec).

The default build mode of HEASoft on Silicon Macs is the native arm64 architecture. Previous HEASoft releases required use of the Rosetta binary translation utility on Apple Silicon hardware, but this restriction was lifted starting with HEASoft 6.31. The default build mode on an Intel Mac is the x86 architecture.

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

A.1. Prerequisites

If they aren't installed already, you will need to install a few system-level packages required for building HEASoft from the source code distribution.

A.1.i. System

X11

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

Compilers: C, C++, Perl, Fortran

We recommend using the Apple XCode C compilers (/usr/bin/clang,clang++,perl).

Apple XCode

For best performance, we recommend using the native Apple C and Perl compilers provided by the XCode Command Line Tools (CLT) (/usr/bin/clang, /usr/bin/clang++, /usr/bin/perl). Note that having out-of-date CLT can result in malfunctions in third-party software (such as the Fortran compiler). Ensure that they are up-to-date with your OS by running:

xcode-select --install

A Fortran compiler

A Fortran compiler is not provided by XCode but can be installed using any of the various Mac package managers. MacPorts and Homebrew are the ones used and tested most at the HEASARC and are therefore recommended above other options. Note also that when updating your Mac OS or XCode version, it is typically necessary to reinstall any third-party packages for compatibility with the new system.

For example, install gfortran from the MacPorts gcc14 package (after installing MacPorts itself): 

sudo port install gcc14
This provides /opt/local/bin/gfortran-mp-14

Or, install gfortran from the Homebrew gcc@14 package (after installing Homebrew itself):

brew install gcc@14
This provides /usr/local/bin/gfortran-14 (on an Intel Mac) or /opt/homebrew/bin/gfortran-14 (on a Silicon Mac).
PNG

If you'd like to use the PNG driver in PGPLOT (the plotting package in HEASoft used by fplot and others), you may also want to install the "libpng" package :

sudo port install libpng
or 
brew install libpng

When configuring heasoft, you may then also need to use this configure option, otherwise the PNG driver in PGPLOT will not be activated:

./configure --with-png=/opt/local
or 
./configure --with-png=/opt/homebrew

A.1.ii. Python

Some tools and interfaces in HEASoft require Python, such as:

If you have no need of any of these HEASoft packages and did not include them in your download, you may forgo installing the Python prerequisites.

HEASoftPy and other packages require Python elements:

  • Python 3.6 (or newer)
  • pip
  • AstroPy (v4.0.0 or newer)
  • NumPy (v1.7.0 or newer)
  • SciPy (v1.5.0 or newer)
  • MatPlotLib

Users who prefer MacPorts may install the Python packages using the following:

sudo port install python312 py312-astropy py312-numpy py312-scipy py312-matplotlib py312-pip

Users who prefer a different Python environment (Miniconda, etc.) may choose to install the Python packages in that environment instead. The following commands install the required Python elements.

conda install astropy numpy scipy matplotlib pip

Note that the HEASoftPy installation uses pip and thus requires access to the internet while building.

A.1.iii. Environment Variables

While the configure script in the next step will try its best to find suitable choices, the safest way to ensure that the correct compilers are used by HEASoft is to set the standard environment variables:

  • CC (C compiler)
  • CXX (C++ compiler)
  • PERL (Perl interpreter)
  • FC (Fortran compiler)
  • PYTHON (Python interpreter).

Replace these paths to the appropriate locations on your machine.

In Bourne shell variants (bash/sh/zsh):

export CC=/usr/bin/clang
export CXX=/usr/bin/clang++
export PERL=/usr/bin/perl
export FC=/opt/homebrew/bin/gfortran-14
export PYTHON=$HOME/miniconda3/bin/python3

In C-shell variants (tcsh/csh):

setenv CC /usr/bin/clang
setenv CXX /usr/bin/clang++
setenv PERL /usr/bin/perl
setenv FC /opt/homebrew/bin/gfortran-14
setenv PYTHON $HOME/miniconda3/bin/python3

If these variables are not used, the HEASoft configure script will attempt to find the necessary items in one of the system directories listed in your PATH environment variable, but success is not guaranteed.

External packages (e.g. Miniconda) may set compiler or other flags in the environment which can negatively impact a HEASoft build, so users are advised to unset all *FLAGS variables. Additionally, Mac users are advised to put the XCode /usr/bin at the front of their PATH (i.e. ahead of any third-party packages that may have inserted themselves into the PATH)

In Bourne shell variants (bash/sh/zsh):

unset CFLAGS CXXFLAGS FFLAGS LDFLAGS build_alias host_alias
export PATH="/usr/bin:$PATH"

In C-shell variants (tcsh/csh):

unsetenv *FLAGS build_alias host_alias
setenv PATH "/usr/bin:$PATH"

Alternatively, users may alter their session to cancel any Miniconda or other package initialization by editing their profile or other shell resource files (.bashrc, .cshrc, etc.).

Other software packages (e.g. XMM-SAS) may change the DYLD_LIBRARY_PATH environment variable, and this can break a HEASoft build, so users are advised to check their DYLD_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. More information about using other software packages such as CIAO and XMM-SAS can be found on the HEASoft known issues page.

A.2. Configure

Before configuring HEASoft, you should commit to the location of the installed 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. The default location of the installed executables are in an architecture-dependent directory underneath the top HEASoft directory. To specify another location for the installed files, use the --prefix option of the configure script.

To see more configure options, run:

./configure --help

Also note that the compiler settings described above will NOT pass to a sudo shell, so if you want to install HEASoft in a protected location (such as /usr/local), you should configure and build the software WITHOUT using sudo in a location writeable by you (e.g. your home directory), and use sudo only when performing the final make install step below.

After the prerequisite packages have been installed and the appropriate environment variables have been set, configure the software. While optional, it is a good idea for future troubleshooting to capture the screen output to text files as shown here.

In Bourne shell variants (bash/sh/zsh):

cd heasoft-6.35.2/BUILD_DIR/
./configure > config.txt 2>&1

In C-shell variants (tcsh/csh):

cd heasoft-6.35.2/BUILD_DIR/
./configure >& config.txt

The configure process may take several minutes to complete. If it is successful, the last line of output (in config.txt) should read "Finished". If it is not successful, do not proceed until any errors have been resolved. Check the HEASoft known issues page for troubleshooting, or contact the help desk.

A.3. Build

If and only if the configure was successful, proceed to build the software. Again, optionally capturing the screen output to a text file for reference may be useful for future troubleshooting.

In Bourne shell variants (bash/sh/zsh): 
make > build.txt 2>&1
In C-shell variants (tcsh/csh): 
make >& build.txt

This process may take an hour or more to run, depending on your hardware and HEASoft download selections. If it is successful, the last line of output (in build.txt) should read "Finished make all". If it is not successful, do not proceed until any errors have been resolved. Check the HEASoft known issues page for troubleshooting, or contact the help desk.

If the build (or the install in the next step) failed and you find it necessary to change the configuration (e.g., by switching compilers), you should run make clean to remove any compiled objects (*.o, libraries, executables) from the failed attempt, then re-run the configure script before restarting make.

A.4. Install

If 'make' was successful, proceed to install the software. Again, optionally capturing the screen output to a text file for reference may be useful for future troubleshooting.

In Bourne shell variants (bash/sh/zsh): 
make install > install.txt 2>&1
In C-shell variants (tcsh/csh): 
make install >& install.txt

This process may take 30-45 minutes to run, depending on your hardware and HEASoft download selections. If it is successful, the last line of output (in install.txt) should read "Finished make install". If it is not successful, do not proceed until any errors have been resolved. Check the HEASoft known issues page for troubleshooting, or contact the help desk.

A.5. Initialize

If the make install step was successful, you may proceed with initializing the software. The following are example commands which you will modify to be appropriate for your system:

In Bourne shell variants (bash/sh/zsh): 
export HEADAS=/path/to/your/installed/heasoft-6.35.2/(PLATFORM)
source $HEADAS/headas-init.sh
In C-shell variants (tcsh/csh): 
setenv HEADAS /path/to/your/installed/heasoft-6.35.2/(PLATFORM)
source $HEADAS/headas-init.csh

In these commands, /path/to/your/installed is a placeholder for the actual directory path on your system identifying the location in which you installed heasoft. By default, the installed location will be in the source code tree directly under the top level heasoft-6.35.2 folder, and (PLATFORM) is a placeholder for the platform-specific string denoting your machine's architecture, for example: x86_64-apple-darwin21.6.0.

The initialization is silent and only generates a message if there is an error. If it is successful, you may begin using the software. For example, type fthelp ftools to see a full listing of possible tools, or type xspec to start the Xspec spectral analysis program.

B. PRE-COMPILED BINARY INSTALLATION

Installations of the traditional pre-compiled binaries are not recommended due to the lack of portability of pre-compiled Perl libraries and other potential portability issues, and the source code distribution has historically been required for users who wish to load local models in Xspec or use the Xspec Python interface (PyXspec).

However, starting with HEASoft version 6.35, HEASoft and Xspec are also distributed as (pre-compiled) conda packages that do allow for using PyXspec and local models in Xspec.

The instructions below assume that you have already downloaded a HEASoft pre-compiled binary tar file and have unpacked it (using e.g. tar zxf [tar file]) on your machine.

B.1. Prerequisites (for Pre-Compiled Binaries)

If they aren't installed already, you will need to install a few system-level packages required for using the pre-compiled HEASoft binary distribution.

System

X11

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

Compilers: C, C++, Perl, Fortran

The HEASoft 6.31 release restored support for the Apple XCode C compilers (/usr/bin/clang,clang++,perl), and we recommend using these:

Apple XCode

For best performance, we recommend using the native Apple C and Perl compilers provided by the XCode Command Line Tools (CLT) (/usr/bin/clang, /usr/bin/clang++, /usr/bin/perl). Note that having out-of-date CLT can result in malfunctions in third-party software (such as the Fortran compiler). Ensure that they are up-to-date with your OS by running:

xcode-select --install

A Fortran compiler

A Fortran compiler is not provided by XCode but can be installed using any of the various Mac package managers. Homebrew and MacPorts are the ones used and tested most at the HEASARC and are therefore recommended above other options. Note also that when updating your Mac OS or XCode version, it is typically necessary to reinstall any third-party packages for compatibility with the new system.

For example, install gfortran from the Homebrew gcc@14 package (after installing Homebrew itself):

brew install gcc@14
This provides /usr/local/bin/gfortran-14 (Intel) or /opt/homebrew/bin/gfortran-14 (Silicon)

Or install gfortran from the MacPorts gcc14 package (after installing MacPorts itself): 

sudo port install gcc14
This provides /opt/local/bin/gfortran-mp-14 (Intel or Silicon)

Python

Some tools and interfaces in HEASoft require Python, such as:

If you have no need of any of these HEASoft packages and did not include them in your download, you may forgo installing the Python prerequisites.

HEASoftPy and other packages require Python elements:

  • Python 3.6 (or newer)
  • pip
  • AstroPy (v4.0.0 or newer)
  • NumPy (v1.7.0 or newer)
  • SciPy (v1.5.0 or newer)
  • MatPlotLib

Users who prefer MacPorts may install the Python packages using the following:

sudo port install python312 py312-astropy py312-numpy py312-scipy py312-matplotlib py312-pip

Users who prefer a different Python environment (Miniconda, etc.) may choose to install the Python packages in that environment instead. The following commands install the required Python elements.

conda install astropy numpy scipy matplotlib pip

B.2. Configure (Pre-Compiled Binaries)

After the prerequisite packages have been installed, the next step is to configure the software. While optional, it is a good idea for future troubleshooting to capture the screen output to text files as shown here.

In Bourne shell variants (bash/sh/zsh): 
cd heasoft-6.35.2/(PLATFORM)/BUILD_DIR/
./configure > config.txt 2>&1
In C-shell variants (tcsh/csh): 
cd heasoft-6.35.2/(PLATFORM)/BUILD_DIR/
./configure >& config.txt

The configure process may take several minutes to complete. If it is successful, the last line of screen output (or the last line in the "config.txt" file) should read "Finished". If it is not successful, do not proceed until any errors have been resolved. Check the HEASoft known issues page for troubleshooting, or contact the help desk.

If the configure script yields a message about a "Perl mismatch", you will either need to install HEASoft from the source code distribution, or install a version of Perl which matches that listed for your platform in our Perl reference.

Build and Install

The binaries are provided pre-built. You do not need to run "make" or "make install." After configuring, the next step is to initialize the software.

B.3. Initialize

If the "configure" step was successful, you may proceed with initializing the software. The following are example commands which you will modify to be appropriate for your system.

In Bourne shell variants (bash/sh/zsh): 
export HEADAS=/path/to/your/installed/heasoft-6.35.2/(PLATFORM)
source $HEADAS/headas-init.sh
In C-shell variants (tcsh/csh): 
setenv HEADAS /path/to/your/installed/heasoft-6.35.2/(PLATFORM)
source $HEADAS/headas-init.csh

In these commands, /path/to/your/installed is a placeholder for the actual directory path on your system identifying the location in which you installed heasoft. By default, the installed location will be in the source code tree directly under the top level heasoft-6.35.2 folder, and (PLATFORM) is a placeholder for the platform-specific string denoting your machine's architecture, for example: x86_64-apple-darwin21.6.0.

The initialization is silent and only generates a message if there is an error. If it is successful, you may begin using the software. For example, type fthelp ftools to see a full listing of possible tools, or type xspec to start the Xspec spectral analysis program.

C. NOTES ON USING INSTALLED SOFTWARE

C.1. Calibration Database (CALDB)

Many HEASoft tasks require access to the CALDB, which is available separately from HEASoft. The simplest way to access the CALDB is remotely, assuming a good internet connection is available. Alternatively, the CALDB may be installed locally on your system.

C.2. Uninstalling HEASoft

For guidance about removing a HEASoft installation from your system, please refer to our uninstall guide.