MPIRUN(1) Open MPI MPIRUN(1) (NAME) mpirun - Open MPI NOTE: mpirun mpiexec . . . (SYNOPSIS) (SPMD): mpirun [ options ] [ ] (MIMD): mpirun [ global_options ] [ local_options1 ] [ ] : [ local_options2 ] [ ] : ... : [ local_optionsN ] [ ] mpirun --prefix mpirun . : shell$ /usr/local/bin/mpirun ... shell$ mpirun --prefix /usr/local (QUICK SUMMARY) MPI : shell$ mpirun [ -n X ] [ --hostfile ] X ( mpirun Open MPI ssh X ) ( ) CPU . . mpirun . ( // ): o (Bind to core): => o (Bind to package): > o (Bind to none): (Oversubscribed) () ( --bind-to none) . OPEN MPI PRRTE (OPEN MPI'S USE OF PRRTE) Open MPI PMIx ( PRRTE) MPI . PRRTE . PRRTE . Open MPI . Open MPI PRRTE PRRTE . . (COMMAND LINE OPTIONS) mpirun Open MPI PRRTE . : mpirun prterun mpirun PRRTE . (No content) Open MPI : o PRRTE . o PRRTE Open MPI . Open MPI PRRTE ( Sphinx configure ) . . ! (OPTIONS) . . https://docs.prrte.org ( ). mpirun . << >> . o : . mpirun . o : . mpirun . (App context) . o -h --help: . o -q --quiet: orterun . o -v --verbose: (). o -V --version: . orterun . o -N : num ( --npernode). o --display-map: . o --display-allocation: . o --output-proctable: . o --dvm: (DVM). o --max-vm-size : . () . v1.8 mpirun ( ) . . . o -H --host : . o --hostfile : . o --default-hostfile : . o --machinefile : --hostfile. o --cpu-set : CPU ( ). -- CPU CPU . . -- N . o -n --n -c -np <#>: . . ( -n ) Open MPI ( << >> PRRTE ). SPMD ( ) . NOTE: -n . o --map-by ppr:N:: N . o --npersocket <#persocket>: . -npersocket --bind-to-socket . ( --map-by ppr:n:package) o --npernode <#pernode>: . ( --map-by ppr:n:node). o --pernode: -- --npernode 1. ( --map-by ppr:1:node) : o --map-by : package . slot hwthread core L1cache L2cache L3cache package numa node seq rankfile pe-list=# ppr. : : o pe=n: n o span: o oversubscribe: o nooversubscribe: () o nolocal: mpirun o hwtcpus: CPU o corecpus: CPU () o file=filename: rankfile filename o ordered: pe-list NOTE: socket package . o --bycore: ( --map-by core). o --byslot: ( --map-by slot). o --nolocal: orterun . --host . --map-by :nolocal. o --nooversubscribe: ( ). <> <> . ( ). --map-by :nooversubscribe. o --oversubscribe: . --map-by :oversubscribe. o --bynode: . MPI_COMM_WORLD . ( --map-by node) o --cpu-list : [=``NULL``]. hwloc . NOTE: lstopo(1) hwloc . MPI_COMM_WORLD: o --rank-by : slot . slot node fill span . : o --bind-to : core . slot hwthread core l1cache l2cache l3cache package numa none . o --cpus-per-proc <#perproc>: CPU. ( --map-by :PE=n) o --cpus-per-rank <#perrank>: --cpus-per-proc. ( --map-by :PE=n) o --bind-to-core: ( --bind-to core) o --bind-to-socket: ( --bind-to package) o --report-bindings: . (Rankfiles): o --rankfile : . ( --map-by rankfile:file=FILE) / : o --output-filename : stdout stderr stddiag . . filename.id id MPI_COMM_WORLD . (cwd) mpirun . mpirun(1) . o --stdin : MPI_COMM_WORLD stdin . stdin 0 MPI_COMM_WORLD stdin . none stdin . o --merge-stderr-to-stdout: stderr stdout . o --tag-output: stdout stderr stddiag [jobid, MCW_rank] (jobid) MPI_COMM_WORLD . o --timestamp-output: (Timestamp) stdout stderr stddiag. o --xml: stdout stderr stddiag XML. o --xml-file : XML . o --xterm : MPI_COMM_WORLD xterm. -1 . . NOTE: xterm . ! xterm . xterm . : xterm (PATH) . ./my_mpi_app my_mpi_app . xterm mpirun (Hang) ctrl-C . . : o --path : . PATH . o --prefix : PATH LD_LIBRARY_PATH Open MPI . . o --noprefix: --prefix. o --preload-binary: () . Open MPI . o --preload-files : . o --set-cwd-to-session-dir: . o --wd : -wdir. o --wdir : . . : --wdir . . o -x : . -x . . : shell$ mpirun -x DISPLAY -x OFILE=/tmp/out ... -x . -x ( ) . MCA: o --gmca : MCA . . o --mca : MCA. MCA . NOTE: Open MPI MCA PMIx PRRTE --mca . MCA PMIx PRRTE --pmixmca --prtemca . o --pmixmca : MCA PMIx. MCA . o --prtemca : MCA PMIx ( PRRTE). MCA . o --tune : (tune file) MCA . << MCA >> . --am --tune . (Debugging): o --get-stack-traces: --timeout mpirun (Stack traces) . . o --timeout : mpirun . mpirun . --timeout --get-stack-traces . : o --allow-run-as-root: mpirun (mpirun ). . o --app : appfile . o --continuous: . o --disable-recovery: ( ). o --do-not-launch: . o --enable-recovery: (: ). o --leave-session-attached: . ( ) . o --max-restarts : . o --personality : [=``ompi``]. o --ppr : (: ). --map-by ppr:N:OBJ. o --report-child-jobs-separately: . o --report-events : URI . o --report-pid : (PID) mpirun . - PID stdout + PID stderr PID . o --report-uri : URI mpirun . - URI stdout + URI stderr URI . o --show-progress: . o --terminate: DVM. o --use-hwthread-cpus: CPU . Open MPI ( slots Slurm) . PRRTE . Open MPI << >> . PRRTE . Open MPI : o --debug-daemons: . o --debug-daemons-file: . o --display-devel-map: . o --display-topo: . o --launch-agent: . prted . mpirun . prted --prtemca odls_base_verbose 5 prted mpirun . o --report-state-on-timeout: --timeout . mpirun --help . (Environment Variables) o MPIEXEC_TIMEOUT: --timeout. (DESCRIPTION) mpirun MPI Open MPI . (SPMD) mpirun . (MIMD) : (Application Context). MIMD . mpirun . . (:) . ( --hostfile) ( -n). (Specifying Host Nodes) mpirun --host (Hostfile) . : shell$ mpirun -H aa,aa,bb ./a.out aa bb . : shell$ cat myhostfile aa slots=2 bb slots=2 cc slots=2 (aa bb cc) . shell$ mpirun --hostfile myhostfile ./a.out . shell$ mpirun --hostfile myhostfile --host aa ./a.out aa . shell$ mpirun --hostfile myhostfile --host dd ./a.out . dd . ( Slurm Torque ) Open MPI . (Specifying Number of Processes) . . . : shell$ mpirun -H aa,bb --map-by ppr:2:package ./a.out 0-3 aa 4-7 bb ( aa bb ). shell$ mpirun -H aa,bb --map-by ppr:2:node ./a.out 0-1 aa 2-3 bb . shell$ mpirun -H aa,bb --map-by ppr:1:node ./a.out . mpirun -H aa,bb --pernode ./a.out --map-by ppr:1:node --npernode 1 . -n . : shell$ cat myhostfile aa slots=4 bb slots=4 cc slots=4 myhostfile: shell$ mpirun --hostfile myhostfile -n 6 ./a.out 0-3 aa 4-5 bb . -n . : (Mapping Processes to Nodes: Using Policies) . mpirun . -n 6 . mpirun MPI_COMM_WORLD : +-----------------+---------+---------+---------+ |Command | Node aa | Node bb | Node cc | +-----------------+---------+---------+---------+ |mpirun | 0 1 2 3 | 4 5 | | +-----------------+---------+---------+---------+ |mpirun --map-by | 0 3 | 1 4 | 2 5 | |node | | | | +-----------------+---------+---------+---------+ |mpirun --nolocal | | 0 1 2 3 | 4 5 | +-----------------+---------+---------+---------+ --map-by node . --nolocal ( aa) . mpirun --nolocal mpirun / . -n (Oversubscribe) . : shell$ mpirun --hostfile myhostfile -n 14 ./a.out 0-3 aa 4-7 bb 8-11 cc . . . : shell$ mpirun --hostfile myhostfile -n 14 --nooversubscribe ./a.out --nooversubscribe . : shell$ cat myhostfile aa slots=4 max_slots=4 bb max_slots=4 cc slots=4 max_slots . slots . : shell$ mpirun --hostfile myhostfile -n 14 ./a.out cc . . --nooversubscribe Open MPI max_slots . -n -H -host . : shell$ mpirun -H aa,bb -n 8 ./a.out . ( aa bb) . MIMD : shell$ mpirun -H aa -n 1 hostname : -H bb,cc -n 2 uptime 0 hostname aa 1 2 uptime bb cc . (Mapping, Ranking, and Binding: Oh My!) Open MPI : 1. (Mapping): 2. (Ranking): MPI_COMM_WORLD 3. (Binding): (Mapper) . . . -- . . << >> . --map-by seq . : shell$ mpirun -hostfile myhostfile --map-by seq ./a.out aa bb cc . . (Rankfile) . . MPI_COMM_WORLD . Open MPI MPI . --np 8 --map-by ppr:2:package --host aa:4,bb:4 : +-----------------------------+-----------+-----------+ | (Option) | Node aa | Node bb | +-----------------------------+-----------+-----------+ |--rank-by fill | 0 1 | 2 3 | 4 5 | 6 7 | |( | | | | - | | | |) | | | +-----------------------------+-----------+-----------+ |--rank-by span | 0 4 | 1 5 | 2 6 | 3 7 | |( | | | | | | | |) | | | +-----------------------------+-----------+-----------+ |--rank-by node | 0 2 | 4 6 | 1 3 | 5 7 | +-----------------------------+-----------+-----------+ fill MCW . span slot -- . node MCW . . . . . . -- l3cache L3 . --bind-to l3cache L3 . --map-by pe-list= . --map-by pe-list=0,2,5 0,2,5 . :ordered --map-by pe-list=0,2,5:ordered . CPU 0 CPU 2 CPU 5 . --report-bindings . . --report-bindings . . shell$ mpirun --np 4 --report-bindings --map-by core --bind-to core [...] Rank 0 bound to package[0][core:0] [...] Rank 1 bound to package[0][core:1] [...] Rank 2 bound to package[0][core:2] [...] Rank 3 bound to package[0][core:3] . shell$ mpirun --np 4 --report-bindings --map-by package --bind-to package [...] Rank 0 bound to package[0][core:0-3] [...] Rank 1 bound to package[0][core:0-3] [...] Rank 2 bound to package[1][core:4-7] [...] Rank 3 bound to package[1][core:4-7] . . fill . shell$ mpirun --np 4 --report-bindings --map-by package --bind-to package --rank-by span [...] Rank 0 bound to package[0][core:0-3] [...] Rank 1 bound to package[1][core:4-7] [...] Rank 2 bound to package[0][core:0-3] [...] Rank 3 bound to package[1][core:4-7] span . shell$ mpirun --np 4 --report-bindings --map-by slot:PE=2 --bind-to core [...] Rank 0 bound to package[0][core:0-1] [...] Rank 1 bound to package[0][core:2-3] [...] Rank 2 bound to package[0][core:4-5] [...] Rank 3 bound to package[0][core:6-7] . slot PE=2 ( ) . Open MPI << >> <<>> --bind-to core . shell$ mpirun --np 4 --report-bindings --map-by slot:PE=2 --use-hwthread-cpus [...]] Rank 0 bound to package[0][hwt:0-1] [...]] Rank 1 bound to package[0][hwt:2-3] [...]] Rank 2 bound to package[0][hwt:4-5] [...]] Rank 3 bound to package[0][hwt:6-7] --bind-to core --use-hwthread-cpus . --use-hwthread-cpus --bind-to hwthread --report-bindings . . shell$ mpirun --np 4 --report-bindings --bind-to none [...] Rank 0 is not bound (or bound to all available processors) [...] Rank 1 is not bound (or bound to all available processors) [...] Rank 2 is not bound (or bound to all available processors) [...] Rank 3 is not bound (or bound to all available processors) . Open MPI . . MCA . mpirun . MCA mpirun mca-params.conf MCA . MCA PRRTE --prtemca ( prte r r) / MCA . / MCA PRTE_MCA_ ( : PRTE PRRTE). : +------------------+------------------------------+---------+ |Option | PRRTE MCA parameter key | Value | +------------------+------------------------------+---------+ |--map-by core | rmaps_default_mapping_policy | core | +------------------+------------------------------+---------+ |--map-by package | rmaps_default_mapping_policy | package | +------------------+------------------------------+---------+ |--rank-by fill | rmaps_default_ranking_policy | fill | +------------------+------------------------------+---------+ |--bind-to core | hwloc_default_binding_policy | core | +------------------+------------------------------+---------+ |--bind-to package | hwloc_default_binding_policy | package | +------------------+------------------------------+---------+ |--bind-to none | hwloc_default_binding_policy | none | +------------------+------------------------------+---------+ (Defaults for Mapping, Ranking, and Binding) --map-by --rank-by --bind-to : o : o : o --map-by core o --bind-to core o --rank-by span o : --map-by core --bind-to core --rank-by span o : o --map-by package o --bind-to package o --rank-by fill o : --map-by package --bind-to package --rank-by fill o --map-by OBJ ( OBJ core ) : o --map-by OBJ o --bind-to OBJ --map-by o --rank-by fill o : --map-by OBJ --bind-to OBJ --rank-by fill o --bind-to OBJ ( OBJ core ) : o --map-by core package o --bind-to OBJ o --rank-by fill o : --map-by OBJ --bind-to OBJ --rank-by fill o --map-by OBJ1 --bind-to OBJ2 : o --map-by OBJ1 o --bind-to OBJ2 o --rank-by fill o : --map-by OBJ2 --bind-to OBJ2 --rank-by fill (hostA hostB) ( []) ( /../) ( .) . --map-by core --bind-to core --rank-by span : shell$ mpirun --np 2 --host hostA:4,hostB:2 ./a.out R0 hostA [BB/../../../../../../..][../../../../../../../..] R1 hostA [../BB/../../../../../..][../../../../../../../..] --map-by package --bind-to package --rank-by fill : shell$ mpirun --np 4 --host hostA:4,hostB:2 ./a.out R0 hostA [BB/BB/BB/BB/BB/BB/BB/BB][../../../../../../../..] R1 hostA [BB/BB/BB/BB/BB/BB/BB/BB][../../../../../../../..] R2 hostA [../../../../../../../..][BB/BB/BB/BB/BB/BB/BB/BB] R3 hostA [../../../../../../../..][BB/BB/BB/BB/BB/BB/BB/BB] --map-by OBJ --bind-to OBJ --rank-by fill . --map-by hwthread --bind-to hwthread --rank-by fill : shell$ mpirun --np 4 --map-by hwthread --host hostA:4,hostB:2 ./a.out R0 hostA [B./../../../../../../..][../../../../../../../..] R1 hostA [.B/../../../../../../..][../../../../../../../..] R0 hostA [../B./../../../../../..][../../../../../../../..] R1 hostA [../.B/../../../../../..][../../../../../../../..] --bind-to OBJ --map-by --rank-by fill . --map-by package --bind-to core --rank-by fill : shell$ mpirun --np 4 --bind-to core --host hostA:4,hostB:2 ./a.out R0 hostA [BB/../../../../../../..][../../../../../../../..] R1 hostA [../BB/../../../../../..][../../../../../../../..] R2 hostA [../../../../../../../..][BB/../../../../../../..] R3 hostA [../../../../../../../..][../BB/../../../../../..] --rank-by fill span . . (span) . : shell$ mpirun --np 4 --bind-to core --rank-by span --host hostA:4,hostB:2 ./a.out R0 hostA [BB/../../../../../../..][../../../../../../../..] R1 hostA [../../../../../../../..][BB/../../../../../../..] R2 hostA [../BB/../../../../../..][../../../../../../../..] R3 hostA [../../../../../../../..][../BB/../../../../../..] (Rankfiles) (Rankfiles) () . ( MPI <<>> MPI_COMM_WORLD ). : rank = slot= : shell$ cat myrankfile rank 0=aa slot=1:0-2 rank 1=bb slot=0:0,1 rank 2=cc slot=2-3 shell$ mpirun -H aa,bb,cc,dd --map-by rankfile:file=myrankfile ./a.out : o 0 aa 1 0-2. o 1 bb 0 0 1. o 2 cc 2 3. . . :hwtcpus --map-by ( --map-by rankfile:file=myrankfile:hwtcpus). . --bind-to :overload-allowed . <<>> . <<>> ( --host mpirun ). <<>> +n X X 0 . : shell$ cat myrankfile rank 0=+n0 slot=1:0-2 rank 1=+n1 slot=0:0,1 rank 2=+n2 slot=2-3 shell$ mpirun -H aa,bb,cc,dd --map-by rankfile:file=myrankfile ./a.out / . NOTE: Open MPI v1.6 . Open MPI v5.0 MCA rmaps_rank_file_physical . lstopo(1) Hwloc . (Application Context or Executable Program?) mpirun --app . (Application Context) . . (Locating Files) Open MPI --path . --path --path Open MPI PATH () . . ssh $HOME . mpirun . (Current Working Directory) --wdir mpirun ( --wd) . / . --wdir . -wdir Open MPI . mpirun . -wdir Open MPI mpirun . . ( ) Open MPI . MPI_INIT(3) . / (Standard I/O) Open MPI (stdin) 0 MPI_COMM_WORLD /dev/null . 0 MPI_COMM_WORLD mpirun . NOTE: mpirun 0 MPI_COMM_WORLD . Open MPI mpirun 0 . Open MPI (stdout stderr) mpirun / mpirun . / mpirun . / Open MPI mpirun . : shell$ mpirun -n 2 my_app < my_input > my_output 0 MPI_COMM_WORLD my_input stdin . stdin /dev/null . stdout my_output . (Signal Propagation) mpirun SIGTERM SIGINT SIGTERM SIGKILL . SIGUSR1 SIGUSR2 mpirun . SIGTSTP mpirun SIGSTOP mpirun SIGCONT mpirun SIGCONT . mpirun . / (Process Termination / Signal Handling) MPI ( MPI_FINALIZE(3) ) mpirun MPI . (Signal handlers) MPI (Open MPI (async-signal-safe) MPI_THREAD_MULTIPLE MPI_INIT_THREAD(3) ). (Segmentation fault) MPI_SEND(3) ( ) MPI_FINALIZE(3) Open MPI <<>> MPI . mpirun ( ) MPI . (Process Environment) MPI PRRTE . . MCA (Boot) . rsh rsh/ssh PRRTE PRRTE . (Dynamically linked) LD_LIBRARY_PATH Open MPI . . (Remote Execution) Open MPI PATH ( rsh ssh -- / PATH / LD_LIBRARY_PATH ). Open MPI LD_LIBRARY_PATH ( MPI ). PATH / LD_LIBRARY_PATH . --prefix . --prefix : Open MPI . Open MPI PATH LD_LIBRARY_PATH Open MPI . Open MPI PATH LD_LIBRARY_PATH . Open MPI (Basename) $bindir ( Open MPI) PATH . Open MPI $libdir ( Open MPI) LD_LIBRARY_PATH . : o bin : /local/node/directory/bin o lib : /local/node/directory/lib64 : shell$ mpirun --prefix /remote/node/directory Open MPI /remote/node/directory/bin PATH /remote/node/directory/lib64 LD_LIBRARY_PATH . --prefix ( /lib /lib64 ) . mpirun --prefix mpirun . : shell$ /usr/local/bin/mpirun ... shell$ mpirun --prefix /usr/local (Exported Environment Variables) OMPI_* . MCA mca_base_env_list . -x mpirun MCA . -x MCA -- . ( ) . MCA (Setting MCA Parameters) --mca MCA ( Modular Component Architecture) . MCA MPI ( BTL BTL ). --mca : . MCA . btl BTL MPI . . : shell$ mpirun --mca btl tcp,self -n 1 my_mpi_app Open MPI BTL tcp self my_mpi_app . shell$ mpirun --mca btl self -n 1 my_mpi_app Open MPI BTL self my_mpi_app . --mca / . (,``) . --mca . mpirun . Open MPI : OMPI_MCA_= --mca . --mca MCA $OPAL_PREFIX/etc/openmpi-mca-params.conf $HOME/.openmpi/mca-params.conf . -- ( mpirun) . -- MCA . MCA ompi_info . ompi_info(1) . MCA (Setting MCA parameters and environment variables from file) --tune --mca mca_base_envar_file_prefix MCA . <<,>> . -x --mca . : o --mca var val o --mca var "val" o -x var=val o -x var . MCA . (Running as root) (WARNING): Open MPI mpirun (root) . MPI ( ) . mpirun . --allow-run-as-root mpirun OMPI_ALLOW_RUN_AS_ROOT=1 OMPI_ALLOW_RUN_AS_ROOT_CONFIRM=1 . --allow-run-as-root Open MPI . ( ) mpirun ( --allow-run-as-root) . : Open MPI . (Exit status) mpirun . mpirun (: <<>> mpirun -- <<>> ): o 0 mpirun 0 . o mpirun MPI_COMM_WORLD . o 0 mpirun: 1. MPI_COMM_WORLD jobid 2. . o --report-child-jobs-separately . . . MCA --prtemca state_base_error_non_zero_exit <> ( <<0>>) Open MPI . Open MPI mpirun ( ) . (EXAMPLES) . shell$ mpirun -n 4 --mca btl tcp,sm,self prog1 prog1 BTL tcp sm ( ) self ( ) MPI. (RETURN VALUE) mpirun mpirun MPI_FINALIZE(3) 0 . mpirun MPI_FINALIZE(3) . mpirun . MPI_FINALIZE(3) MPI_COMM_WORLD mpirun MPI_FINALIZE(3) . . --timeout ( mpirun ) mpirun ETIMEDOUT ( OS X ) . (SEE ALSO): MPI_INIT(3), MPI_INIT_THREAD(3), MPI_FINALIZE(3), ompi_info(1) (COPYRIGHT) 2003-2026, The Open MPI Community February 23, 2026 MPIRUN(1)