Installing HEASoft on Linux

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

See also the video walkthrough describing the installation process. The video was created using a Mac, but many of the steps are the same.

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 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

For Debian-based Linux (e.g. Ubuntu), use the "apt-get" utility:

sudo apt-get -y install libreadline-dev
sudo apt-get -y install libncurses5-dev     # or "libncurses-dev"
sudo apt-get -y install ncurses-dev
sudo apt-get -y install curl
sudo apt-get -y install libcurl4
sudo apt-get -y install libcurl4-gnutls-dev
sudo apt-get -y install xorg-dev
sudo apt-get -y install make
sudo apt-get -y install gcc g++ gfortran
sudo apt-get -y install perl-modules
sudo apt-get -y install libdevel-checklib-perl
sudo apt-get -y install libfile-which-perl
sudo apt-get -y install python3-dev         # or "python-dev"
sudo apt-get -y install python3-pip
sudo apt-get -y install python3-setuptools
sudo apt-get -y install python3-astropy     # needed for IXPE
sudo apt-get -y install python3-numpy       # needed for IXPE
sudo apt-get -y install python3-scipy       # needed for IXPE
sudo apt-get -y install python3-matplotlib  # needed for IXPE
sudo pip install --upgrade pip              # NOT needed in Ubuntu 24.04
sudo /usr/bin/python3 -m pip install --upgrade pip

Or, in a single copy-and-pastable line (apt-get command only, excludes the pip command):

sudo apt-get -y install libreadline-dev libncurses5-dev ncurses-dev curl \
libcurl4 libcurl4-gnutls-dev xorg-dev make gcc g++ gfortran perl-modules \
libdevel-checklib-perl libfile-which-perl python3-dev python3-pip python3-setuptools \
python3-astropy python3-numpy python3-scipy python3-matplotlib

For RPM-based Linux (e.g. Fedora), use the "dnf" (formerly "yum") utility:

sudo dnf -y install redhat-rpm-config
sudo dnf -y install readline-devel
sudo dnf -y install ncurses-devel
sudo dnf -y install zlib-devel
sudo dnf -y install libcurl-devel
sudo dnf -y install libXt-devel
sudo dnf -y install make
sudo dnf -y install gcc gcc-c++
sudo dnf -y install gcc gcc-gfortran        # or "gcc gcc-fortran"
sudo dnf -y install perl-devel
sudo dnf -y install perl-Devel-CheckLib
sudo dnf -y install perl-DirHandle
sudo dnf -y install perl-Env
sudo dnf -y install perl-ExtUtils-MakeMaker
sudo dnf -y install perl-File-Which
sudo dnf -y install python3-devel           # or "python-devel"
sudo dnf -y install python3-astropy         # needed for IXPE
sudo dnf -y install python3-numpy           # needed for IXPE
sudo dnf -y install python3-matplotlib      # needed for IXPE
sudo pip3 install --only-binary=:all: scipy --upgrade

Or, in a single copy-and-pastable line (dnf command only, excludes the pip3 command):

sudo dnf -y install redhat-rpm-config readline-devel ncurses-devel \
zlib-devel libcurl-devel libXt-devel make gcc gcc-c++ gcc gcc-gfortran \
perl-devel perl-Devel-CheckLib perl-DirHandle perl-Env perl-ExtUtils-MakeMaker \
perl-File-Which python3-devel python3-astropy python3-numpy python3-matplotlib

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

If you prefer to use a different Python environment (Miniconda, etc.), you may choose to install the Python packages (AstroPy, NumPy, SciPy, MatPlotLib) in that environment instead. The following commands install the required Python elements.

In Bourne shell variants (bash/sh/zsh): 
conda install astropy numpy scipy matplotlib pip
export PYTHON=$HOME/miniconda3/bin/python3
In C-shell variants (tcsh/csh): 
conda install astropy numpy scipy matplotlib pip
setenv PYTHON $HOME/miniconda3/bin/python3

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)
  • FC (Fortran compiler)
  • PERL (Perl interpreter)
  • PYTHON (Python interpreter)
In Bourne shell variants (bash/sh/zsh): 
export CC=/usr/bin/gcc
export CXX=/usr/bin/g++
export FC=/usr/bin/gfortran
export PERL=/usr/bin/perl
export PYTHON=/usr/bin/python3
In C-shell variants (tcsh/csh): 
setenv CC /usr/bin/gcc
setenv CXX /usr/bin/g++
setenv FC /usr/bin/gfortran
setenv PERL /usr/bin/perl
setenv PYTHON /usr/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 and conda alias variables.

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 LD_LIBRARY_PATH environment variable, and this can break a HEASoft build, so users are advised to check their 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. 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-pc-linux-gnu-libc2.32.

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

For Debian-based Linux (e.g. Ubuntu), use the "apt-get" utility:

sudo apt-get -y install libreadline-dev
sudo apt-get -y install libncurses5-dev     # or "libncurses-dev"
sudo apt-get -y install xorg-dev
sudo apt-get -y install python3-dev         # or "python-dev"
sudo apt-get -y install python3-pip
sudo apt-get -y install python3-setuptools
sudo apt-get -y install python3-astropy
sudo apt-get -y install python3-numpy
sudo apt-get -y install python3-scipy
sudo apt-get -y install python3-matplotlib
sudo pip install --upgrade pip              # NOT needed in Ubuntu 24.04

For RPM-based Linux (e.g. Fedora), use the "dnf" (formerly "yum") utility:

sudo dnf -y install readline-devel
sudo dnf -y install ncurses-devel
sudo dnf -y install libXt-devel
sudo dnf -y install python3-devel           # or "python-devel"
sudo dnf -y install python3-astropy
sudo dnf -y install python3-numpy
sudo dnf -y install python3-matplotlib
sudo pip3 install --only-binary=:all: scipy --upgrade

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

If you prefer to use a different Python environment (Miniconda, etc.), you may choose to install the Python packages (AstroPy, NumPy, SciPy, MatPlotLib) in that environment instead. The following commands install the required Python elements.

In Bourne shell variants (bash/sh/zsh): 
conda install astropy numpy scipy matplotlib pip
export PYTHON=$HOME/miniconda3/bin/python3
In C-shell variants (tcsh/csh): 
conda install astropy numpy scipy matplotlib pip
setenv PYTHON $HOME/miniconda3/bin/python3

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 (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.

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-pc-linux-gnu-libc2.32.

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.