mpiexec(1)

👑 NAME 👑

mpiexec — run an MPI program. yeah. that's the whole job bestie 💅

---

🦋 SYNOPSIS 🦋

mpiexec args executable pgmargs [ : args executable pgmargs ... ]

okay so let's break that down fr fr:

• args = command line arguments for mpiexec (all of them are down below, keep scrolling 🙈)
• executable = the name of an executable MPI program
• pgmargs = command line arguments for the executable

and you can stack multiple executables by using the colon notation (that's for MPMD — Multiple Program Multiple Data applications, iconic behavior ✨)

like, this one runs the MPI program a.out on 4 processes:

mpiexec -n 4 a.out

The MPI standard suggests the following arguments and their meanings — aka the standard's starter pack 🎀

• -n <np> — specify the number of processes to use
• -host <hostname> — name of host on which to run processes
• -wdir <working directory> — cd to this one before running executable
• -configfile <name> — file containing command-line options. The lines are of the form separated by the colons in the commandline form:

mpiexec {<option arguments>} : {...} : {...} : ... : {...}

Lines beginning with # are comments, and lines may be continued by terminating the partial line with a continuation marker (the manpage shows this spot as blank, no cap, that's just how it printed 😭)

⚠️ okay so these next ones — the following options are reserved by the MPI standard, but they are not supported by MPICH (hydra). so like. don't come for hydra about it, it simply does not do these 🫶

• -arch <architecture name> — pick hosts with this architecture type
• -path <pathlist> — use this to find the executable
• -soft <triplets> — comma separated triplets that specify requested numbers of processes (see the MPI-2 specification for more details)
• -file <name> — implementation-defined specification file

Additional arguments that are specific to the MPICH implementation are discussed below 👇

The colon character ( : ) may be used to separate different executables for MPMD (multiple program multiple data) programming. for example, to run the program ocean on 4 processes and air on 8 processes, use:

mpiexec -n 4 ocean : -n 8 air

see? colon = the lil glow-up separator 💖

---

🌈 MPICH-SPECIFIC ARGUMENTS 🌈

MPICH implements a few process managers. Here we list a general set of arguments that many of the implementations support. More detailed options that are supported by a particular implementation, e.g. hydra, are available via:

mpiexec -h

💡 lowkey the move is always mpiexec -h before you start guessing, bestie. the specific manager tells you its specific secrets ✨

Many of the implementations of process managers in MPICH support the following arguments to mpiexec:

• -np <num> — a synonym for the standard -n argument
• -env <name> <value> — set the environment variable <name> to <value> for the processes being run by mpiexec
• -envnone — pass no environment variables (other than ones specified with other -env or -genv arguments) to the processes being run by mpiexec

By default, all environment variables are provided to each MPI process (rationale: principle of least surprise for the user) 😌

• -envlist <list> — pass the listed environment variables (names separated by commas), with their current values, to the processes being run by mpiexec
• -genv <name> <value> — the -genv options have the same meaning as their corresponding -env version, except they apply to all executables, not just the current executable (in the case that the colon syntax is used to specify multiple executables)
• -genvnone — like -envnone, but for all executables
• -genvlist <list> — like -envlist, but for all executables
• -usize <n> — specify the value returned for the value of the attribute MPI_UNIVERSE_SIZE
• -l — label standard out and standard error ( stdout and stderr ) with the rank of the process
• -maxtime <n> — set a timelimit of <n> seconds
• -exitinfo — provide more information on the reason each process exited if there is an abnormal exit

---

🍓 ENVIRONMENT VARIABLES FOR MPIEXEC 🍓

The following environment variables are understood by some versions of mpiexec. The command line arguments have priority over these; that is, if both the environment variable and command line argument are used, the value specified by the command line argument is used. 💅 (command line stays winning, as it should)

• MPIEXEC_TIMEOUT — maximum running time in seconds. mpiexec will terminate MPI programs that take longer than the value specified by MPIEXEC_TIMEOUT.
• MPIEXEC_UNIVERSE_SIZE — set the universe size
• MPIEXEC_PORT_RANGE — set the range of ports that mpiexec will use in communicating with the processes that it starts. The format of this is <low>:<high> . For example, to specify any port between 10000 and 10100, use 10000:10100 .
• MPICH_PORT_RANGE — has the same meaning as MPIEXEC_PORT_RANGE and is used if MPIEXEC_PORT_RANGE is not set.

---

⭐ RETURN STATUS ⭐

mpiexec returns the maximum of the exit status values of all of the processes created by mpiexec . so whichever process was the messiest, that's the number you get 😭

---

🎀 LOCATION 🎀

/var/tmp/vc8XKeIJUJ/mpich-5.0.1/src/pm/hydra/mansrc/mpiexec.txt

---

and that's the whole page, bestie!! 🦋 this one lives in the HYDRA manual set, the file itself is part of MPICH 5.0.1, and it was dated 4/10/2026 — so you know exactly which version you're reading. periodt. 💖✨👑