Developer Installation

note:Feedback welcome

These instructions were recently updated. If anything is unclear or you have suggestions for improvement, please share your feedback in this GitHub discussion.

The following instructions describe how to compile MOOSE or MOOSE-based applications from source. If you are not modifying MOOSE source, we suggest that you first start with User Installation to install a pre-built version of MOOSE.

MOOSE requires a complex set of dependencies (see Required Dependencies) to be built. While these dependencies can be installed by the developer, we provide a variety of development environments that reduce the need for these dependencies to be installed. These development environments are not required to build an application but greatly simplify the process of doing so.

First, you need to clone MOOSE or the MOOSE-based application that you wish to build and possibly develop. For the purposes of these instructions, we will assume that you are trying to build MOOSE. However, if you were given separate instructions for obtaining a MOOSE-based application, follow those instead. If not, follow the instructions in Cloning MOOSE.

After obtaining a git checkout of the MOOSE or MOOSE-based application you are developing, follow the instructions based on your operating system and/or environment below:

Cloning MOOSE

MOOSE is hosted on GitHub and should be cloned from there using git.

We recommend creating a projects directory to contain your cloned applications. Thus, the first two commands in the commands that follow will involve acting within the projects directory.

note:Cloning on Windows

If using Windows, first follow the installation instructions for installing WSL first in Windows Install. The following commands can then be ran within the WSL Ubuntu window so that the repository is cloned within the WSL space.

note:Cloning on INL HPC

On INL HPC, internet access is not available on compute nodes. That is, you can only perform git operations (including the operation that follows) like git clone, git push, git pull, and git fetch on a login node.

It is also suggested to clone and build applications within the scratch space instead. On INL HPC machines, your scratch directory is found at /scratch/USERNAME where USERNAME is your HPC username. File system performance on scratch is significantly faster than performance within your home directory. However, files stored within scratch may be deleted when they are more than 90 days old. Thus, be sure to copy content from scratch that you do not want to lose.

To clone MOOSE, run the following commands:


mkdir -p ~/projects
cd ~/projects
git clone --origin upstream https://github.com/idaholab/moose.git
cd moose
git checkout devel

For the instructions that follow, when we reference the "MOOSE repository", we are considering the repository you just cloned which is found at ~/projects/moose.

If you plan on contributing code changes to MOOSE, you will need to fork the GitHub repository and contribute changes via pull requests and your fork. For contributing code changes, you should base your pull request branches on the devel branch.

Installation

Choose the installation section that follows depending on your operating system and environment.

Linux Install

The preferred method of installation on Linux is using the pre-built development environment using Apptainer.

Developer Install: Apptainer (preferred)
- Use Apptainer to execute in development environment containers.
- Contains optional dependencies (libTorch, MFEM, NEML2).
Developer Install: Conda (Linux)
- Use Conda to distribute the development environment.
- Does not contain optional dependencies (libTorch, MFEM, NEML2).

INL HPC Install

These instructions describe building on INL HPC resources.

Developer Install: INL HPC
- Use modules on INL HPC that provide convenient access to a containerized development environment.
- Contains optional dependencies (libTorch, MFEM, NEML2).

Mac OS Install

We generally advise against the use of Homebrew on Mac OS. Intel Macs are currently still supported but this support will end at the end of 2026 as software updates to these machines are reduced to only security updates.

Developer Install: Conda (Mac) (preferred)
- Use Conda to distribute the development environment.
- Does not contain optional dependencies (libTorch, MFEM, NEML2).

Windows Install

Developer Install: Conda (Windows) (preferred)
- Use Conda to distribute the development environment within WSL (Windows Subsystem for Linux).
- Does not contain optional dependencies (libTorch, MFEM, NEML2).
- Support is limited.

Dependencies

Required Dependencies

The required dependencies for MOOSE are as follows:

C and C++17 compiler

A compiler for building C and C++ code. The preferred compilers are:

GCC: tested on versions 9.2.1, 13.3.1, 14.3.0
Clang: tested on versions 19.1.7, 20.1.8

Fortran compiler

A compiler for building Fortran code. The preferred compiler is:

GCC: tested on versions 9.2.1, 13.3.1, 14.3.0

GNU Make

GNU Make is used to execute Makefile files for building applications.

MPI

Message Passing Interface (MPI) is a portable message-passing standard to execute applications in parallel. The preferred implementations are:

MPICH: tested on versions 4.3.2, 5.0.1
OpenMPI: tested on version 5.0.10

PETSc

PETSc, the Portable, Extensible Toolkit for Scientific Computation, is for the scalable (parallel) solution of scientific applications modeled by partial differential equations (PDEs).

The currently supported version is v3.25.1. Other versions are not guaranteed to be compatible.

Pre-built distributions of PETSc are found in the distributed development environments via Apptainer, Conda, and Docker. Thus, PETSc does not need to be built with these environments.

If not using pre-built development environments from Apptainer, Conda, and Docker, PETSc can be installed via the (scripts/update_and_rebuild_petsc.sh) script within the MOOSE repository. By default, this script will install PETSc to ./petsc/arch-moose relative to the MOOSE repository root.

libMesh

libMesh provides a framework for mesh definition and finite-element assembly.

The currently supported commit is aeab0b9. Other commits are not guaranteed to be compatible.

Pre-built distributions of libMesh are found in the distributed development environments via Apptainer, Conda, and Docker. Thus, libMesh does not need to be built with these environments.

If not using pre-built development environments from Apptainer, Conda, and Docker, PETSc can be installed via the (scripts/update_and_rebuild_libmesh.sh) script within the MOOSE repository. By default, this script will install libMesh to ./libmesh/installed relative to the MOOSE repository root. This script requires PETSc to also be installed, where the PETSc directory is defined by the environment variable $PETSC_DIR or is installed in ./petsc/arch-moose relative to the MOOSE repository root.

Python

Python versions 3.10 - 3.14 are supported.

WASP

WASP is used as the backend for parsing MOOSE input files and also provides the language server for interacting with MOOSE input.

The currently supported commit is 09054a2. Other commits are not guaranteed to be compatible.

Pre-built distributions of PETSc are found in the distributed development environments via Apptainer, Conda, and Docker. Thus, WASP does not need to be built with these environments.

If not using pre-built development environments from Apptainer, Conda, and Docker, WASP can be installed via the (scripts/update_and_rebuild_wasp.sh) script within the MOOSE repository. This script requires CMake for configuration. By default, this script will install WASP to ./framework/contrib/wasp/install relative to the MOOSE repository root.

Optional Dependencies

Conduit at commit 4ae5a69 (required by MFEM)
NEML2 at commit 9b8d8b9
MFEM at commit e52948f (requires Conduit)
VTK version 9.6.1

(scripts/update_and_rebuild_petsc.sh)

#!/usr/bin/env bash
#* This file is part of the MOOSE framework
#* https://mooseframework.inl.gov
#*
#* All rights reserved, see COPYRIGHT for full restrictions
#* https://github.com/idaholab/moose/blob/master/COPYRIGHT
#*
#* Licensed under LGPL 2.1, please see LICENSE for details
#* https://www.gnu.org/licenses/lgpl-2.1.html

function exitIfExitCode() {
    # When --with-packages-download-dir=path is used, PETSc will print out how to
    # download external packages. A system code 10 is used in this case. We should
    # not consider it as error.
    if [ $1 -eq 10 ]; then
        exit 0
    elif [ $1 -ne 0 ]; then
        printf "There was an error. Exiting...\n"
        exit 1
    fi
}

PFX_STR=''
# Set go_fast flag if "--fast" is found in command line args.
for i in "$@"
do
  shift
  if [ "$i" == "--fast" ]; then
    go_fast=1;
  fi

  if [[ "$i" == "-h" || "$i" == "--help" ]]; then
    help=1;
  fi

  if [ "$i" == "--skip-submodule-update" ]; then
    skip_sub_update=1;
  else # Remove the skip submodule update argument before passing to PETSc configure
    set -- "$@" "$i"
  fi

  # If users specify "--prefix", we need to make install
  if [[ "$i" == "--prefix="* ]]; then
    PFX_STR=$i
  fi
done

SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
echo $SCRIPT_DIR

if [ -n "$PETSC_SRC_DIR" ]; then
  skip_sub_update=1
else
  MOOSE_DIR=${SCRIPT_DIR}/..
  PETSC_SRC_DIR=${MOOSE_DIR}/petsc
fi

# Display help
if [[ -n "$help" ]]; then
  echo "Usage: $0 [-h | --help | --fast | --skip-submodule-update | <PETSc options> ]"
  echo
  echo "-h | --help              Display this message and list of available PETSc options"
  echo "--fast                   Run PETSc 'make all' only, do NOT run configure"
  echo "--skip-submodule-update  Do not update the PETSc submodule, use the current version"
  echo "*************************************************************************************"
  echo ""

  if [ -e "${PETSC_SRC_DIR}/configure" ]; then
    cd ${PETSC_SRC_DIR}
    ./configure -h
  fi
  exit 0
fi


if [[ -n "$go_fast" && $# != 1 ]]; then
  echo "Error: --fast can only be used by itself or with --skip-submodule-update."
  echo "Try again, removing either --fast or all other conflicting arguments!"
  exit 1;
fi

# Set PETSc envir
export PETSC_DIR=${PETSC_SRC_DIR}
if [ -z "$PETSC_ARCH" ]; then
    export PETSC_ARCH=arch-moose
fi


# Test for git repository when not using fast
if [ -z "$skip_sub_update" ]; then
  cd ${MOOSE_DIR}
  git_dir=`git rev-parse --show-cdup 2>/dev/null`
  if [[ -z "$go_fast" && $? == 0 && "x$git_dir" == "x" ]]; then
    git submodule update --init --recursive petsc
    if [[ $? != 0 ]]; then
      echo "git submodule command failed, are your proxy settings correct?"
      exit 1
    fi
  fi
fi

# Set installation prefix if given
if [ ! -z "$PETSC_PREFIX" ]; then
  PFX_STR="--prefix=$PETSC_PREFIX"
fi

cd ${PETSC_SRC_DIR}

# If we're not going fast, remove the build directory and reconfigure
if [ -z "$go_fast" ]; then
  rm -rf ${PETSC_SRC_DIR}/$PETSC_ARCH

  source $SCRIPT_DIR/configure_petsc.sh
  configure_petsc "$PFX_STR" "$@"

  exitIfExitCode $?
fi

make all
exitIfExitCode $?

if [ ! -z "$PFX_STR" ]; then
  make install
  exitIfExitCode $?
fi

exit 0

(scripts/update_and_rebuild_libmesh.sh)

#!/usr/bin/env bash
#* This file is part of the MOOSE framework
#* https://mooseframework.inl.gov
#*
#* All rights reserved, see COPYRIGHT for full restrictions
#* https://github.com/idaholab/moose/blob/master/COPYRIGHT
#*
#* Licensed under LGPL 2.1, please see LICENSE for details
#* https://www.gnu.org/licenses/lgpl-2.1.html

DIAGNOSTIC_LOG="libmesh_diagnostic.log"

SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

# Set go_fast flag if "--fast" is found in command line args.
for i in "$@"
do
  shift
  if [ "$i" == "--fast" ]; then
    go_fast=1;
  fi

  if [[ "$i" == "-h" || "$i" == "--help" ]]; then
    help=1;
  fi

  if [ "$i" == "--skip-submodule-update" ]; then
    skip_sub_update=1;
  elif [ "$i" == "--quiet-build" ]; then
    quiet_build=1;
    quiet_build_logfile="$SCRIPT_DIR/libmesh_build_$(date +%Y-%m-%d.%H:%M:%S).log"
  else # Remove everything else before passing to configure
    set -- "$@" "$i"
  fi
done

if [ -n "$LIBMESH_SRC_DIR" ]; then
  skip_sub_update=1
else
  MOOSE_DIR=${SCRIPT_DIR}/..
  LIBMESH_SRC_DIR=${MOOSE_DIR}/libmesh
fi

# Display help
if [[ -n "$help" ]]; then
  echo "Usage: $0 [-h | --help | --fast | --skip-submodule-update | --quiet-build | <libmesh options> ]"
  echo
  echo "-h | --help              Display this message and list of available libmesh options"
  echo "--fast                   Run libmesh 'make && make install' only, do NOT run configure"
  echo "--skip-submodule-update  Do not update the libMesh submodule, use the current version"
  echo "--quiet-build            Only output the build (make and make install) to screen on failure"
  echo "*************************************************************************************"
  echo ""

  if [ -x "${LIBMESH_SRC_DIR}/configure" ]; then
    "${LIBMESH_SRC_DIR}/configure" -h
  fi
  exit 0
fi

# If --fast was used, it means we are going to skip configure, so
# don't allow the user to pass any other flags (with the exception
# of --skip-submodule-update) to the script thinking they are going
# to do something.
if [[ -n "$go_fast" && $# != 1 ]]; then
  echo "Error: --fast can only be used by itself or with --skip-submodule-update."
  echo "Try again, removing either --fast or all other conflicting arguments!"
  exit 1;
fi


# generate machine diagnostics and write it to the log
$SCRIPT_DIR/diagnostics.sh > "$SCRIPT_DIR/$DIAGNOSTIC_LOG"

# Checks whether or not LIBMESH_DIR is a child of the conda base
function check_libmesh_dir_in_conda()
{
  type conda &> /dev/null || return
  CONDA_BASE="$(conda info --base)" 2> /dev/null || return
  LIBMESH_DIR_ABS="$(readlink -f $LIBMESH_DIR)" 2> /dev/null || return
  if [[ "$LIBMESH_DIR_ABS" == "$CONDA_BASE"* ]]; then
    echo "ERROR: LIBMESH_DIR=$LIBMESH_DIR exists within the conda base $CONDA_BASE"
    echo "Exiting in order to stop you from overwriting your conda environment"
    exit 1
  fi
}

if [[ -n "$LIBMESH_DIR" ]]; then
  check_libmesh_dir_in_conda

  echo "INFO: LIBMESH_DIR set - overriding default installed path"
  echo "INFO: No cleaning will be done in specified path"
  mkdir -p $LIBMESH_DIR
else
  export LIBMESH_DIR=${LIBMESH_SRC_DIR}/installed
  rm -rf ${LIBMESH_SRC_DIR}/installed
fi

# If the user set METHOD, but not METHODS, we'll let METHOD override
# METHODS in this script. Otherwise, METHODS has a default in configure_libmesh.sh
if [[ -n "$METHOD" && -z "$METHODS" ]]; then
  export METHODS="$METHOD"
fi

# If the user has VTK available via our modules, we'll build with VTK
VTK_OPTIONS=""
if [[ -n "$VTKLIB_DIR" && -n "$VTKINCLUDE_DIR" ]]; then
  export VTK_OPTIONS="--with-vtk-lib=$VTKLIB_DIR --with-vtk-include=$VTKINCLUDE_DIR"
fi

# Test for git repository when not using fast
if [ -n "$MOOSE_DIR" ] && [ -z "$skip_sub_update" ]; then
  cd ${MOOSE_DIR}
  git_dir=`git rev-parse --show-cdup 2>/dev/null`
  if [[ -z "$go_fast" && $? == 0 && "x$git_dir" == "x" ]]; then
    git submodule update --init --recursive libmesh
    if [[ $? != 0 ]]; then
      echo "git submodule command failed, are your proxy settings correct?"
      # TODO: is this a git bug?
      # failed attempts with `git submodule update` deletes the submodule directory.
      # So re-create it to prevent a diff.
      mkdir libmesh
      exit 1
    fi
  fi
fi

# check if the user has ccache configured
DISABLE_TIMESTAMPS=""
echo $CXX | cut -d ' ' -f1 | grep '^ccache$' > /dev/null
if [ $? == 0 ]; then
  echo -n "ccache detected - "
  # check if timestamps are explicitly enabled
  echo "$* " | grep -- '--enable-timestamps ' > /dev/null
  if [ $? == 0 ]; then
    echo "warning: setting --enable-timestamps explicitly will negatively impact the ccache performance"
  else
    echo "configuring libmesh with --disable-timestamps to improve cache hit rate"
    DISABLE_TIMESTAMPS="--disable-timestamps"
  fi
fi

cd ${LIBMESH_SRC_DIR}

# If PETSC_DIR is not set in the environment (perhaps because the user is not using the MOOSE
# package), we use the PETSc submodule
if [ -z "$PETSC_DIR" ]; then
  echo "PETSc submodule will be used. PETSc submodule is our default solver."
  echo "IMPORTANT: If you did not run the update_and_rebuild_petsc.sh script yet, please run it before building libMesh"
  export PETSC_DIR=$SCRIPT_DIR/../petsc
  if [ -z "$PETSC_ARCH" ]; then
    export PETSC_ARCH=arch-moose
  fi
fi

# If we're not going fast, remove the build directory and reconfigure
if [ -z "$go_fast" ]; then
  if [[ -n "$LIBMESH_BUILD_DIR" ]]; then
    echo "INFO: LIBMESH_BUILD_DIR set - overriding default build path"
  else
    export LIBMESH_BUILD_DIR=${LIBMESH_SRC_DIR}/build
  fi
  rm -rf $LIBMESH_BUILD_DIR
  mkdir -p $LIBMESH_BUILD_DIR
  cd $LIBMESH_BUILD_DIR

  source $SCRIPT_DIR/configure_libmesh.sh
  SRC_DIR=${LIBMESH_SRC_DIR} configure_libmesh $DISABLE_TIMESTAMPS \
                                               $VTK_OPTIONS \
                                               $* | tee -a "$SCRIPT_DIR/$DIAGNOSTIC_LOG" || exit 1
else
  # The build directory must already exist: you can't do --fast for
  # an initial build.
  if [ ! -d build ]; then
    echo "Error: You have no pre-existing build directory, so you can't use --fast."
    echo "Try running the script again without this flag."
    exit 1;
  fi

  cd build
fi

if [[ -n "$quiet_build" ]]; then
  echo ""
  echo "Quiet build enabled (--quiet-build)"
  echo "Build output will be redirected to" $quiet_build_logfile "and will only be shown on failure"
  echo ""
  echo "Building quietly... this will take some time"
  echo ""
fi

# let LIBMESH_JOBS be either MOOSE_JOBS, or 1 if MOOSE_JOBS
# is not set (not using our package). Make will then build
# with either JOBS if set, or LIBMESH_JOBS.
LIBMESH_JOBS=${MOOSE_JOBS:-1}

# Helper for running build commands that allows us to redirect
# output to $quiet_build_logfile if --quiet-build is set
function run_build_cmd()
{
  echo "Running" $@"..."
  if [[ -n "$quiet_build" ]]; then
    $@ &> "$quiet_build_logfile"
    exit_code=$?
    if [ $exit_code -ne 0 ]; then
      echo ""
      echo "Quiet build failed, printing output of "$quiet_build_logfile":"
      echo ""
      cat "$quiet_build_logfile"
      exit 1;
    fi
  else
    $@ || exit 1
  fi
}

if [ -z "${MOOSE_MAKE}" ]; then
  run_build_cmd make -j ${JOBS:-$LIBMESH_JOBS}
  run_build_cmd make -j ${JOBS:-$LIBMESH_JOBS} install
else
  run_build_cmd ${MOOSE_MAKE}
  run_build_cmd ${MOOSE_MAKE} install
fi

if [[ -n "$quiet_build" ]]; then
  echo "Quiet build succeeded!"
fi

# Local Variables:
# sh-basic-offset: 2
# sh-indentation: 2
# End:

(scripts/update_and_rebuild_wasp.sh)

#!/usr/bin/env bash
#* This file is part of the MOOSE framework
#* https://mooseframework.inl.gov
#*
#* All rights reserved, see COPYRIGHT for full restrictions
#* https://github.com/idaholab/moose/blob/master/COPYRIGHT
#*
#* Licensed under LGPL 2.1, please see LICENSE for details
#* https://www.gnu.org/licenses/lgpl-2.1.html

SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"

if [ -n "$WASP_SRC_DIR" ]; then
  SKIP_SUBMODULE_UPDATE=1
else
  MOOSE_DIR=${SCRIPT_DIR}/..
  WASP_SRC_DIR=${MOOSE_DIR}/framework/contrib/wasp
fi

# Loop over specified command line arguments and turn on any found options
for ARG in "$@" ; do
  if   [[ "${ARG}" == "--help" ]]                  ; then HELP=1
  elif [[ "${ARG}" == "--fast" ]]                  ; then FAST=1
  elif [[ "${ARG}" == "--skip-submodule-update" ]] ; then SKIP_SUBMODULE_UPDATE=1
  else                                               EXTRA_ARGS+=("$ARG")
  fi
done

# Display the help menu to show the list of available options if requested
if [[ -n "${HELP}" ]] ; then
  echo "Usage: $0 [ --help | --fast | --skip-submodule-update ]"
  echo
  echo "--help                   Display this message listing the options that are available"
  echo "--skip-submodule-update  Do not update the WASP submodule, use the current version"
  echo "--fast                   Run WASP 'make install' only and do NOT update or configure"
  echo "*********************************************************************"
  echo
  exit 0
fi

# If we are going fast then check and make sure the build directory exists
if [[ -n "${FAST}"  ]] ; then
  if [[ ! -d "${WASP_SRC_DIR}"/build ]] ; then
    echo "Error: a build directory must exist to use the --fast option"
    exit 1
  fi
  cd "${WASP_SRC_DIR}"/build
# If we are not going fast then update WASP, remove build, and reconfigure
else
  if [ -z "$SKIP_SUBMODULE_UPDATE" ]; then
    cd $MOOSE_DIR
    git submodule update --init --recursive "${WASP_SRC_DIR}"
    if [[ $? -ne 0 ]] ; then
      echo "Error: git submodule update failed to complete successfully"
      mkdir -p "${WASP_SRC_DIR}"
      exit 1
    fi
  fi

  rm -rf "${WASP_SRC_DIR}"/build
  mkdir -p "${WASP_SRC_DIR}"/build
  cd "${WASP_SRC_DIR}"/build
  WASP_OPTIONS="-DCMAKE_INSTALL_PREFIX:STRING=${WASP_PREFIX:-${WASP_SRC_DIR}/install}"
  source $SCRIPT_DIR/configure_wasp.sh
  configure_wasp "$WASP_OPTIONS" ../ "${EXTRA_ARGS[@]}"
  if [[ $? -ne 0 ]] ; then
    echo "Error: configure step for WASP failed to complete successfully"
    exit 1
  fi
fi

# Build with MOOSE_JOBS jobs if defined, otherwise build with a single job
make -j ${MOOSE_JOBS:-1} install
if [[ $? -ne 0 ]] ; then
  echo "Error: build step for WASP failed to complete successfully"
  exit 1
fi
exit 0

Cloning MOOSE
Installation
Dependencies