---
name: "mpiexec"
section: "1"
platform: "linux"
package: "mpich-doc"
version: "4.0.2-3"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/mpiexec"
---

# mpiexec(1)

Run an MPI program

## NAME

mpiexec -  Run an MPI program

## SYNOPSIS

```

```

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

where  *args* are command line arguments for  *mpiexec* (see below), *executable* is the name of an executable MPI program, and  *pgmargs* are command line arguments for the executable.  Multiple executables can be specified by using the colon notation (for MPMD - Multiple Program Multiple Data applications).   For example, the following command will run the MPI program  *a.out* on 4 processes:

```
mpiexec -n 4 a.out
```

The MPI standard specifies the following arguments and their meanings:

- **-n \<np\>**

  \- Specify the number of processes to use

- **-host \<hostname\>**

  \- Name of host on which to run processes

- **-arch \<architecture name\>**

  \- Pick hosts with this architecture type

- **-wdir \<working directory\>**

  \- cd to this one  **before** running executable

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

- **-configfile \<name\>**

  \- file containing specifications of host/program, one per line, with # as a comment indicator, e.g., the usual mpiexec input, but with ":" replaced with a newline.  That is, the configfile contains lines with -soft, -n etc.

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

  Note that not all of these parameters are meaningful for all systems.  For example, the  *gforker* version of  *mpiexec* creates all processes on the same system on which it is running; in that case, the *\\-arch* and  *\\-host* options are ignored.

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

## MPICH-SPECIFIC ARGUMENTS

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.

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

- **MPIEXEC\_PREFIX\_DEFAULT**

  \- If this environment variable is set, output to standard output is prefixed by the rank in  *MPI\_COMM\_WORLD* of the  process and output to standard error is prefixed by the rank and the  text  *(err)* ; both are followed by an angle bracket ( *\>* ).  If this variable is not set, there is no prefix.

- **MPIEXEC\_PREFIX\_STDOUT**

  \- Set the prefix used for lines sent to standard output.  A  *%d* is replaced with the rank in  *MPI\_COMM\_WORLD* ; a  *%w* is  replaced with an indication of which  *MPI\_COMM\_WORLD* in MPI jobs that involve multiple  *MPI\_COMM\_WORLD* s (e.g., ones that use  *MPI\_Comm\_spawn* or *MPI\_Comm\_connect* ).

- **MPIEXEC\_PREFIX\_STDERR**

  \- Like  *MPIEXEC\_PREFIX\_STDOUT* , but for standard error.

## RETURN STATUS

*mpiexec* returns the maximum of the exit status values of all of the processes created by  *mpiexec* .