ALPS Installation on Mac/Linux from Sources

sudo apt update
sudo apt install build-essential cmake \
                   libhdf5-dev \
                   libopenblas-dev \
                   libopenmpi-dev openmpi-bin # or: libmpich-dev mpich

# install Python libs:
pip install numpy scipy # python libraries 
# or 
python3 -m pip install numpy scipy

Do not install Boost via apt. ALPS must compile Boost from source instead — see Boost Error Details in Troubleshooting for why, and how to build offline.

brew update
brew install cmake hdf5 \
               openblas open-mpi # or: mpich

# install Python libs:
pip3 install numpy scipy

Do not install Boost via Homebrew. ALPS must compile Boost from source instead — see Boost Error Details in Troubleshooting for why, and how to build offline.

sudo port selfupdate
sudo port install cmake \
                   hdf5 \
                   OpenBLAS \
                   openmpi-clang20   # see note below about choosing a variant
sudo port select --set mpi openmpi-clang20-fortran

# install Python libs:
pip3 install numpy scipy

Do not install openmpi-clang20 without checking your compiler. See Other Error Details in Troubleshooting for how to pick the right OpenMPI variant.

Do not install Boost via MacPorts. ALPS must compile Boost from source instead — see Boost Error Details in Troubleshooting for why, and how to build offline.

• Boost/Python ABI mismatch
  To avoid an ABI issue, make sure the Python version your Boost was built against is similar to the Python version being used to build ALPS. Consider rebuilding a stale Boost library.
• Check which Python is actually being used
  Confirm the path of the Python CMake selects matches the version you expect. Keep in mind there can be several Pythons on one machine — Homebrew, conda, the OS-provided one (Linux distro Python or Apple’s bundled Python), etc. — and CMake may not pick the one you intended.
  • A virtual environment inserts another Python path ahead of the others in your PATH, which can silently corrupt the build if it’s active without you noticing.
  • When in doubt, CMake should probably be pointed at the native Python that ships with your OS rather than one of these alternates.
• Check CMakeCache.txt
  After configuring, grep the cache in your build directory to see exactly which Python CMake locked in:

  grep -i python build/CMakeCache.txt
  Compare that against the Python you actually intend to build against:

  which python3
  python3 -c "import sys; print(sys.executable)"
  If they don’t match, delete the build directory and set explicitly by reconfiguring with: -DPython3_EXECUTABLE=/path/to/python3.

• Version Compatibility
  Building ALPS’ Python bindings against NumPy ≥ 2.0 requires Boost ≥ 1.87 (NumPy 2.0 introduced API changes that only Boost 1.87+ handles). Boost 1.76–1.86 work only with NumPy < 2.0. See the build notes for tested compiler/Boost/Python combinations.

• Do not install Boost via apt, Homebrew, or MacPorts
  ALPS must compile Boost from source for two reasons:

  1. Custom compiler flags — ALPS requires -DBOOST_NO_AUTO_PTR and -DBOOST_FILESYSTEM_NO_CXX20_ATOMIC_REF for C++17/20 compatibility; package-manager Boost builds do not set these, causing link errors.
  2. Python-ABI match — the Boost.Python component must be compiled against the exact Python interpreter that ALPS will use. Package-manager Boost builds target their own bundled Python and will silently mismatch any other interpreter.

  CMake handles both automatically: if Boost_SRC_DIR is not set, it downloads and compiles Boost 1.87 during configuration (requires internet access). To build offline or reuse a previously extracted archive, download it manually first:

  curl -LO https://archives.boost.io/release/1.87.0/source/boost_1_87_0.tar.gz
  tar -xzf boost_1_87_0.tar.gz

• Need a different MPI or BLAS?
  Substitute the package names above with your cluster’s module (e.g. Intel MKL/OneAPI, AMD AOCL, etc). Cmake is a build system that will find the locations of the above packages and generate compilation instructions in Makefiles.
• Python errors
  Ensure Python ≥ 3.9 is installed and that numpy and scipy are installed for the same Python that CMake selects. On macOS, CMake may pick the Xcode-bundled Python rather than your Homebrew/MacPorts Python — check the Found Python: line in the CMake output and pin the interpreter with -DPython3_EXECUTABLE=/path/to/python3 if needed (see the Verify Dependencies step).
• MPI mismatch?
  Ensure that CMake is using the same MPI version as mpirun --version
• Choosing a MacPorts OpenMPI variant
  MacPorts ships a separate port for each compiler version, named openmpi-<compiler><version> (e.g. openmpi-clang20, openmpi-gcc15). The clang20 variant matches the LLVM Clang 20 port and works alongside Apple’s Xcode clang. If you use a different compiler, install the matching variant and adjust the port select command accordingly. The port select step is required: without it, the bare mpirun, mpicc, and mpicxx wrappers that CMake looks for will not exist.