Include MPI.H Not Found | Fix Build Errors Fast

Guide / By

Include mpi.h not found means your compiler can’t see MPI headers; install an MPI package and compile with its wrapper tools or include paths.

You hit Build, and the compiler stops at the first line that pulls in MPI. It’s frustrating, but the fix is usually plain: the headers exist somewhere on disk, yet your build is not looking there, or MPI is not installed at all.

This guide walks you through a clean set of checks and fixes for Linux, macOS, and Windows, plus the build-system tweaks that trip people up. You’ll end with a command you can run, a path you can verify, and a simple way to confirm the build is linked to the same MPI you plan to run.

What The mpi.h not found message means

The error is a preprocessor failure. When the compiler reads #include , it searches its include directories. If it can’t find that header, it stops. That’s all it is.

If you see include mpi.h not found in your build log, treat it as a search-path issue, not a code bug.

What makes it tricky is that MPI headers rarely live in a “standard” include folder. Many MPI installs tuck headers under a versioned directory, or they rely on wrapper compilers to inject the right -I flags automatically. On Windows, headers may sit under a vendor folder and only Visual Studio projects that point there will compile.

Three common root causes

  • MPI isn’t installed — Your system has no MPI headers, so every compile fails the same way.
  • You used the wrong compiler command — You called gcc/g++ directly instead of mpicc/mpicxx, so the include flags never got added.
  • Your project points at the wrong MPI — You installed one MPI, then your build system is still configured for a different one, or a stale path.

Fast Checks That Save Time Before You Change Anything

Start with checks that don’t touch your system. You want to learn what’s already installed, where headers live, and which compiler wrapper you’re using. These steps keep your next fix targeted.

  1. Check for wrapper compilers — Run mpicc --version and mpicxx --version. If the command is missing, MPI is not on your PATH.
  2. Ask the wrapper for flags — Run mpicc -show (Open MPI) or mpicc -showme. You should see include flags like -I….
  3. Locate the header file — On Linux/macOS, try locate mpi.h or find /usr -name mpi.h 2>/dev/null | head. You’re hunting for a real path you can paste into your build.
  4. Confirm you’re building MPI code — A few libraries ship files named mpi.h that are not full MPI. The safe check is that mpicc reports a vendor like Open MPI, MPICH, Intel MPI, or MS-MPI.

Quick decision table

What you see Likely cause Next step
mpicc not found MPI not installed or PATH not set Install MPI, then reopen your terminal
mpicc -show has no -I Broken install or wrong wrapper Reinstall MPI or switch to a standard package
mpi.h exists under a vendor folder Build lacks include path Add that folder to include directories

Fix Mpi.h Missing Errors For GCC And Clang Builds

On Unix-like systems, the cleanest fix is to stop calling the system compiler directly. MPI wrapper compilers are designed for this exact job. They supply the include paths, libraries, and link flags in the right order.

Use the wrapper compiler on the command line

  1. Compile C with mpicc — Run mpicc -O2 hello.c -o hello instead of gcc.
  2. Compile C++ with mpicxx — Run mpicxx -O2 hello.cpp -o hello instead of g++.
  3. Run with mpirun or mpiexec — Try mpirun -n 2 ./hello so the runtime matches the compile-time MPI.

When you must call gcc or clang

Some build systems hard-code the compiler, or a project needs a specific toolchain. In that case, copy the flags from the wrapper into your build settings.

  • Print the full compile line — Run mpicc -show (or -showme) and copy the -I and -L parts into your build.
  • Add the include directory — Put the folder that contains mpi.h into your include search path, often via -I/path/to/include.
  • Link the matching MPI libs — If you add include paths by hand, also link the right libraries, or you’ll trade a header error for linker errors.

Linux Fixes For Open MPI, MPICH, And Intel MPI

Most Linux setups get MPI from a package manager, a module system on a cluster, or a vendor installer. The steps below aim at the most common cases and keep your build consistent.

Install Open MPI or MPICH from your distro

If you are on Ubuntu or Debian, you can install Open MPI with the packages that provide both runtime and development headers. Many distros split those parts, so grabbing only the runtime leaves out headers.

  • Install Open MPI dev packages — Use your package manager to install Open MPI plus the development headers, then confirm mpicc exists.
  • Install MPICH dev packages — If you prefer MPICH, install its development package and use its mpicc wrapper.
  • Verify the header path — Run mpicc -show and confirm it points at a folder that contains mpi.h.

Open MPI’s own quick-start page lists common install routes like distro packages and Homebrew/MacPorts for macOS. It also shows that wrapper compilers are the normal workflow. You can check the latest guidance in Open MPI’s docs. Open MPI installation quick start.

Handle versioned include directories

Some packages place headers under a versioned folder, not directly under /usr/include. That’s fine when you use mpicc. It fails when you call the base compiler without extra flags.

  1. Find the actual folder — Locate mpi.h and copy the directory name, not the file path.
  2. Add it once — Put that directory into your build include paths and rebuild.
  3. Remove stale paths — If you previously pointed at a different MPI, delete those old -I entries so you don’t mix headers.

macOS Fixes With Homebrew And MacPorts

macOS users often install Open MPI through Homebrew or MacPorts. Both routes give you wrapper compilers, and those wrappers are the simplest path out of the header error.

Install and confirm the wrapper compilers

  1. Install Open MPI — With Homebrew, run brew install openmpi. With MacPorts, run sudo port install openmpi.
  2. Confirm the tool is reachable — Run mpicc --version and make sure it prints vendor info.
  3. Build with mpicc — Re-run your build, pointing the project at mpicc/mpicxx.

Include MPI.H Not Found On Windows With Visual Studio Or VS Code

Windows builds usually fail because the project does not know where MS-MPI (or another MPI) is installed. The fix is to install a Windows MPI distribution, then point the compiler and linker at its include and lib folders.

Install MS-MPI and find its folders

Microsoft MPI installs under C:\\Program Files\\Microsoft MPI by default on many systems. You can download it from Microsoft’s site and install both the SDK and runtime. Microsoft MPI download.

  1. Install the MS-MPI SDK — The SDK includes headers like mpi.h and import libraries.
  2. Locate the include folder — Look for a path like C:\\Program Files\\Microsoft MPI\\Inc.
  3. Locate the lib folder — Look for Lib\\x64 or Lib\\x86, matching your target.

Set Visual Studio project properties

  • Add include directory — In C/C++ settings, add the MS-MPI Inc folder to Additional Include Directories.
  • Add library directory — In Linker settings, add the matching MS-MPI Lib folder to Additional Library Directories.
  • Link the import library — Add msmpi.lib to Additional Dependencies for the linker.

Make, CMake, And IDE Fixes That Prevent The Error From Returning

Once you can build from a terminal, lock it into your project so the error doesn’t reappear on the next machine or CI run. These fixes keep the build repeatable.

Makefiles and plain compiler variables

  • Set CC and CXX to wrappers — Use CC=mpicc and CXX=mpicxx so targets inherit MPI flags.
  • Keep flags minimal — Let wrappers decide the right include paths; add only your project’s own -I folders.
  • Pin the runtime — Use mpirun or mpiexec from the same MPI install you compiled against.

CMake with find_package

CMake can locate MPI via its built-in module, then supply include dirs and libraries to your targets. That is usually cleaner than hard-coded paths.

  1. Enable MPI in CMake — Use find_package(MPI REQUIRED) in your CMakeLists.txt.
  2. Attach MPI to targets — Link your target with MPI::MPI_C or MPI::MPI_CXX so include directories propagate.
  3. Point CMake at the right wrappers — If discovery fails, set CMAKE_C_COMPILER to mpicc and rerun configuration.

When you share the project, include a note that names the MPI vendor and version you built with. Teammates can match it and avoid mismatched runs.

Multi-MPI systems and header mixing

It’s common to have Open MPI and MPICH installed side by side. Header mixing is where build pain starts: compile against one, run with another, and you get runtime crashes or weird hangs.

  • Confirm which mpicc is active — Run which mpicc and keep it stable during your build.
  • Check the runtime tool — Run which mpirun or which mpiexec and ensure it is from the same tree.
  • Clear caches — Delete CMake cache files or your build directory after switching MPI vendors.

Verify The Fix And Avoid The Next Break

When the header error is gone, do one last round of checks so you know your program is wired to the MPI you expect. This takes two minutes and saves hours later.

Build and run a tiny test

  1. Compile a hello program — Build a minimal MPI hello world using the same command your project uses.
  2. Run with two ranks — Execute mpirun -n 2 ./hello (or mpiexec -n 2 hello.exe on Windows) and confirm you see output from rank 0 and rank 1.
  3. Print the MPI version — Call MPI_Get_version in your test and print it to confirm which MPI you are running.

Common traps that bring the error back

  • IDE using a different compiler — Your terminal build may use mpicc while your IDE uses plain gcc. Point the IDE at the wrapper, or copy flags from mpicc -show.
  • Mixing 32-bit and 64-bit libs — On Windows, include and lib folders must match the architecture you build.

If you still see the mpi.h not found error after these steps, treat it as a path problem: locate the real header, then make the compiler search that directory, either through the wrapper compilers or explicit include settings. Once that path is stable, the error goes away and stays away.