IQTREE3-MPI(1)

📦 version 3.1.1, in ubuntu stonking

🦋 iqtree3-mpi(1) — User Commands 🦋

okay bestie, so this is the manual page for iqtree3-mpi, section 1 of the User Commands. it's giving efficient phylogenetic software by maximum likelihood, but it's the multiprocessor version. slay. 💅

🌸 NAME 🌸

iqtree3-mpi — efficient phylogenetic software by maximum likelihood (multiprocessor version). periodt. 💖

✨ SYNOPSIS ✨

iqtree [-s ALIGNMENT] [-p PARTITION] [-m MODEL] [-t TREE] ...

💫 DESCRIPTION 💫

IQ-TREE MPI version 3.1.1 for Linux x86 64-bit built Jul 28 2026. no cap.

Developed by Bui Quang Minh, Thomas Wong, Nhan Ly-Trong, Huaiyan Ren.

Contributed by Lam-Tung Nguyen, Dominik Schrempf, Chris Bielow, Olga Chernomor, Michael Woodhams, Diep Thi Hoang, Heiko Schmidt. iconic. 👑

✨ GENERAL OPTIONS ✨

-h, --help — print (more) help usages. 💖
-s FILE[,...,FILE] — PHYLIP/FASTA/NEXUS/CLUSTAL/MSF alignment file(s).
-s DIR — directory of alignment files.
--seqtype STRING — BIN, DNA, AA, NT2AA, CODON, MORPH (default: auto-detect).
-t FILE|PARS|RAND — starting tree (default: 99 parsimony and BIONJ).
-o TAX[,...,TAX] — outgroup taxon (list) for writing .treefile.
--prefix STRING — prefix for all output files (default: aln/partition).
--seed NUM — random seed number, normally used for debugging purpose.
--safe — safe likelihood kernel to avoid numerical underflow.
--mem NUM[G|M|%] — maximal RAM usage in GB | MB | %.
--runs NUM — number of indepedent runs (default: 1). (yes, "indepedent" is in the original, keep it)
-v, --verbose — verbose mode, printing more messages to screen.
-V, --version — display version number.
--quiet — quiet mode, suppress printing to screen (stdout).
-fconst f1,...,fN — add constant patterns into alignment (N=no. states).
--epsilon NUM — likelihood epsilon for parameter estimate (default 0.01).
-T NUM|AUTO — no. cores/threads or AUTO-detect (default: 1).
--threads-max NUM — max number of threads for -T AUTO (default: all cores).

🔄 CHECKPOINT 🔄

--redo — redo both ModelFinder and tree search.
--redo-tree — restore ModelFinder and only redo tree search.
--undo — revoke finished run, used when changing some options.
--cptime NUM — minimum checkpoint interval (default: 60 sec and adapt).

🧩 PARTITION MODEL 🧩

-p FILE|DIR — NEXUS/RAxML partition file or directory with alignments. Edge-linked proportional partition model.
-q FILE|DIR — like -p but edge-linked equal partition model.
-Q FILE|DIR — like -p but edge-unlinked partition model.
-S FILE|DIR — like -p but separate tree inference.
--subsample NUM — randomly sub-sample partitions (negative for complement).
--subsample-seed NUM — random number seed for --subsample.

🗺️ LIKELIHOOD/QUARTET MAPPING 🗺️

--lmap NUM — number of quartets for likelihood mapping analysis.
--lmclust FILE — NEXUS file containing clusters for likelihood mapping.
--quartetlh — print quartet log-likelihoods to .quartetlh file.

🌳 TREE SEARCH ALGORITHM 🌳

--ninit NUM — number of initial parsimony trees (default: 100).
--ntop NUM — number of top initial trees (default: 20).
--nbest NUM — number of best trees retained during search (default: 5).
-n NUM — fix number of iterations to stop (default: OFF).
--nstop NUM — number of unsuccessful iterations to stop (default: 100).
--perturb NUM — perturbation strength for randomized NNI (default: 0.5).
--radius NUM — radius for parsimony SPR search (default: 6).
--allnni — perform more thorough NNI search (default: OFF).
-g FILE — (multifurcating) topological constraint tree file.
--fast — fast search to resemble FastTree.
--polytomy — collapse near-zero branches into polytomy.
--tree-fix — fix -t tree (no tree search performed).
--treels — write locally optimal trees into .treels file.
--show-lh — compute tree likelihood without optimisation.
--terrace — check if the tree lies on a phylogenetic terrace.

⚡ ULTRAFAST BOOTSTRAP/JACKKNIFE ⚡

-B, --ufboot NUM — replicates for ultrafast bootstrap (>=1000).
-J, --ufjack NUM — replicates for ultrafast jackknife (>=1000).
--jack-prop NUM — subsampling proportion for jackknife (default: 0.5).
--sampling STRING — GENE|GENESITE resampling for partitions (default: SITE).
--boot-trees — write bootstrap trees to .ufboot file (default: none).
--wbtl — like --boot-trees but also writing branch lengths.
--nmax NUM — maximum number of iterations (default: 1000).
--nstep NUM — iterations for UFBoot stopping rule (default: 100).
--bcor NUM — minimum correlation coefficient (default: 0.99).
--beps NUM — RELL epsilon to break tie (default: 0.5).
--bnni — optimize UFBoot trees by NNI on bootstrap alignment.

🎀 NON-PARAMETRIC BOOTSTRAP/JACKKNIFE 🎀

-b, --boot NUM — replicates for bootstrap + ML tree + consensus tree.
-j, --jack NUM — replicates for jackknife + ML tree + consensus tree.
--jack-prop NUM — subsampling proportion for jackknife (default: 0.5).
--bcon NUM — replicates for bootstrap + consensus tree.
--bonly NUM — replicates for bootstrap only.
--tbe — transfer bootstrap expectation.

🌿 SINGLE BRANCH TEST 🌿

--alrt NUM — replicates for SH approximate likelihood ratio test.
--alrt 0 — parametric aLRT test (Anisimova and Gascuel 2006).
--abayes — approximate Bayes test (Anisimova et al. 2011).
--lbp NUM — replicates for fast local bootstrap probabilities.

🔍 MODEL-FINDER 🔍

--use-nn-model — use neural network for tree inference.
--nn-path-model — neural network file for substitution model (onnx format).
--nn-path-rates — neural network file for alpha value (onnx format).
-m TESTONLY — standard model selection (like jModelTest, ProtTest).
-m TEST — standard model selection followed by tree inference.
-m MF — extended model selection with FreeRate heterogeneity.
-m MFP — extended model selection followed by tree inference.
-m ...+LM — additionally test Lie Markov models.
-m ...+LMRY — additionally test Lie Markov models with RY symmetry.
-m ...+LMWS — additionally test Lie Markov models with WS symmetry.
-m ...+LMMK — additionally test Lie Markov models with MK symmetry.
-m ...+LMSS — additionally test strand-symmetric models.
--mset STRING — restrict search to models supported by other programs (raxml, phyml, mrbayes, beast1 or beast2). If mrbayes is selected, will output a MrBayes Block File if Data Type is supported.
--mset STR,... — comma-separated model list (e.g. -mset WAG,LG,JTT).
--msub STRING — amino-acid model source (nuclear, mitochondrial, chloroplast or viral).
--mfreq STR,... — list of state frequencies.
--mrate STR,... — list of rate heterogeneity among sites (e.g. -mrate E,I,G,I+G,R is used for -m MF).
--cmin NUM — min categories for FreeRate model [+R] (default: 2).
--cmax NUM — max categories for FreeRate model [+R] (default: 10).
--merit AIC|AICc|BIC — Akaike|Bayesian information criterion (default: BIC).
--mtree — perform full tree search for every model.
--madd STR,... — list of mixture models to consider.
--mdef FILE — model definition NEXUS file (see Manual).
--modelomatic — find best codon/protein/DNA models (Whelan et al. 2015).

🧩 PARTITION-FINDER 🧩

--merge — merge partitions to increase model fit.
--merge greedy|rcluster|rclusterf — set merging algorithm (default: rclusterf).
--merge-model 1|all — use only 1 or all models for merging (default: 1).
--merge-model STR,... — comma-separated model list for merging.
--merge-rate 1|all — use only 1 or all rate heterogeneity (default: 1).
--merge-rate STR,... — comma-separated rate list for merging.
--rcluster NUM — percentage of partition pairs for rcluster algorithm.
--rclusterf NUM — percentage of partition pairs for rclusterf algorithm.
--rcluster-max NUM — max number of partition pairs (default: 10*partitions).

🧬 SUBSTITUTION MODEL 🧬

-m STRING — model name string (e.g. GTR+F+I+G). 💅 now here's the tea on what STRING can be:
- DNA: HKY (default), JC, F81, K2P, K3P, K81uf, TN/TrN, TNef, TIM, TIMef, TVM, TVMef, SYM, GTR, or 6-digit model specification (e.g., 010010 = HKY)
- Protein: LG (default), Poisson, cpREV, mtREV, Dayhoff, mtMAM, JTT, WAG, mtART, mtZOA, VT, rtREV, DCMut, PMB, HIVb, HIVw, JTTDCMut, FLU, Blosum62, GTR20, mtMet, mtVer, mtInv, FLAVI, Q.LG, Q.pfam, Q.pfam_gb, Q.bird, Q.mammal, Q.insect, Q.plant, Q.yeast
- Protein mixture: C10,...,C60, EX2, EX3, EHO, UL2, UL3, EX_EHO, LG4M, LG4X
- Binary: JC2 (default), GTR2
- Empirical codon: KOSI07, SCHN05
- Mechanistic codon: GY (default), MG, MGK, GY0K, GY1KTS, GY1KTV, GY2K, MG1KTS, MG1KTV, MG2K
- Semi-empirical codon: XX_YY where XX is empirical and YY is mechanistic model
- Morphology/SNP: MK (default), ORDERED, GTR
- Lie Markov DNA: 1.1, 2.2b, 3.3a, 3.3b, 3.3c, 3.4, 4.4a, 4.4b, 4.5a, 4.5b, 5.6a, 5.6b, 5.7a, 5.7b, 5.7c, 5.11a, 5.11b, 5.11c, 5.16, 6.6, 6.7a, 6.7b, 6.8a, 6.8b, 6.17a, 6.17b, 8.8, 8.10a, 8.10b, 8.16, 8.17, 8.18, 9.20a, 9.20b, 10.12, 10.34, 12.12 (optionally prefixed by RY, WS or MK)
- Non-reversible: STRSYM (strand symmetric model, equiv. WS6.6), NONREV, UNREST (unrestricted model, equiv. 12.12) NQ.pfam, NQ.bird, NQ.mammal, NQ.insect, NQ.plant, NQ.yeast
- Otherwise: Name of file containing user-model parameters

🎚️ STATE FREQUENCY 🎚️

-m ...+F — empirically counted frequencies from alignment.
-m ...+FO — optimized frequencies by maximum-likelihood.
-m ...+FQ — equal frequencies.
-m ...+FRY — for DNA, freq(A+G)=1/2=freq(C+T).
-m ...+FWS — for DNA, freq(A+T)=1/2=freq(C+G).
-m ...+FMK — for DNA, freq(A+C)=1/2=freq(G+T).
-m ...+Fabcd — 4-digit constraint on ACGT frequency (e.g. +F1221 means f_A=f_T, f_C=f_G).
-m ...+FU — amino-acid frequencies given protein matrix.
-m ...+F1x4 — equal NT frequencies over three codon positions.
-m ...+F3x4 — unequal NT frequencies over three codon positions.

🔥 RATE HETEROGENEITY AMONG SITES 🔥

-m ...+I — a proportion of invariable sites.
-m ...+G[n] — discrete Gamma model with n categories (default n=4).
-m ...*G[n] — discrete Gamma model with unlinked model parameters.
-m ...+I+G[n] — invariable sites PLUS the Gamma model, with n rate categories, bestie 💖
-m ...+R[n] — FreeRate model with n categories (default n=4) 🎀
-m ...*R[n] — FreeRate model, but the model parameters are unlinked 👀
-m ...+I+R[n] — invariable sites + FreeRate model with n categories, the whole combo meal ✨
-m ...+Hn — Heterotachy model with n classes 🦋
-m ...*Hn — Heterotachy model with n classes AND unlinked parameters 🔓
--alpha-min NUM — minimum Gamma shape parameter for site rates (default: 0.02)
--gamma-median — median approximation for +G site rates (default is mean, fyi)
--rate — writes the empirical Bayesian site rates into a .rate file 📝
--mlrate — writes maximum likelihood site rates into a .mlrate file 📝

🧬 POLYMORPHISM AWARE MODELS (PoMo) 🧬

-s FILE — input counts file (go read the manual for this one, bestie)
-m ...+P — a DNA substitution model (see above ⬆️) used together with PoMo
-m ...+N<POPSIZE> — virtual population size (default: 9)
-m ...+WB|WH|S] — weighted binomial sampling
-m ...+WH — weighted hypergeometric sampling
-m ...+S — sampled sampling
-m ...+G[n] — discrete Gamma rate with n categories (default n=4) 🌈

💅 COMPLEX MODELS 💅

-m "MIX{m1,...,mK}" — mixture model with K components
-m "FMIX{f1,...fK}" — frequency mixture model with K components
--mix-opt — optimize the mixture weights (default: detect) ⚖️
-m ...+ASC — ascertainment bias correction
--tree-freq FILE — input tree used to infer the site frequency model 🌳
--site-freq FILE — input site frequency model file
--freq-max — posterior maximum instead of the mean approximation

🔥 TREE TOPOLOGY TEST 🔥

--trees FILE — a set of trees whose log-likelihoods get evaluated
--test NUM — number of replicates for the topology test
--test-weight — perform weighted KH and SH tests
--test-au — approximately unbiased (AU) test (Shimodaira 2002)
--au-epsilon NUM — epsilon for the AU test: if |deltaL| < NUM, the tree is kept no matter what the p-value says (default: 0.001)
--sitelh — write site log-likelihoods into a .sitelh file

🌸 ANCESTRAL STATE RECONSTRUCTION 🌸

--ancestral — ancestral state reconstruction via empirical Bayes 🕰️
--asr-min NUM — minimum probability of an ancestral state (default: equil freq)

👑 TEST OF SYMMETRY 👑

--symtest — perform three tests of symmetry
--symtest-only — do --symtest then exist
--symtest-remove-bad — do --symtest and remove the bad partitions 🗑️
--symtest-remove-good — do --symtest and remove the good partitions 🗑️
--symtest-type MAR|INT — use the MARginal/INTernal test when removing partitions
--symtest-pval NUMER — p-value cutoff (default: 0.05)
--symtest-keep-zero — keep the NAs in the tests 🫶

🦋 CONCORDANCE FACTOR ANALYSIS 🦋

-t FILE — reference tree to assign the concordance factor to
--gcf FILE — set of source trees for the gene concordance factor (gCF)
--df-tree — write the discordant trees associated with gDF1
--scf NUM — number of quartets for the site concordance factor (sCF)
--scfl NUM — like --scf but using likelihood (recommended, fr fr ⭐)
-s FILE — sequence alignment for --scf
-p FILE|DIR — partition file or directory for --scf
--cf-verbose — write CF per tree/locus into cf.stat_tree/_loci
--cf-quartet — write the sCF for all resampled quartets into .cf.quartet

🧚 ALISIM: ALIGNMENT SIMULATOR 🧚

Usage: iqtree --alisim <OUTPUT_PREFIX> [-m MODEL] [-t TREE] ...

--alisim OUTPUT_ALIGNMENT — activate AliSim and pick the output alignment filename ✨
-t TREE_FILE — set the input tree file name
--length LENGTH — set the length of the root sequence
--num-alignments NUMBER — set the number of output datasets
--seqtype STRING — BIN, DNA, AA, CODON, MORPH{NUM_STATES} (default: auto-detect). For morphological data, 0<NUM_STATES<=32 💀
--m MODEL_STRING — specify the evolutionary model. See the Manual for way more detail
--mdef FILE — name of a NEXUS model file used to define new models (see Manual)
--fundi TAXA_LIST,RHO — specify a list of taxa, and Rho (the Fundi weight) for the FunDi model
--indel <INS>,<DEL> — set the insertion and deletion rate of the indel model, relative to the substitution rate
--indel-size <INS_DIS>,<DEL_DIS> — set the insertion and deletion size distributions
--sub-level-mixture — enable the feature that simulates a substitution-level mixture model
--no-unaligned — stop outputting a file of unaligned sequences when indel models are in play
--root-seq FILE,SEQ_NAME — specify the root sequence from an alignment
-s FILE — specify the input sequence alignment
--no-copy-gaps — stop copying gaps from the input alignment (default: false)
--site-freq <OPTION> — pick the option (MEAN (default), or SAMPLING, or MODEL) to mimic the site-frequencies for mixture models from the input alignment (see Manual)
--site-rate <OPTION> — pick the option (MEAN (default), or SAMPLING, or MODEL) to mimic the discrete rate heterogeneity from the input alignment (see Manual)
-t RANDOM{MODEL,NUM_TAXA} — specify the model and the number of taxa to generate a random tree 🌳
-rlen MIN MEAN MAX — specify three numbers: minimum, mean and maximum branch lengths when generating a random tree
-p FILE — NEXUS/RAxML partition file, edge-linked proportional partition model
-q FILE — like -p but edge-linked equal partition model
-Q FILE — like -p but edge-unlinked partition model
--distribution FILE — supply a definition file of distributions, which could be used to generate random model parameters
--branch-distribution DIS — specify a distribution, from which branch lengths of the input trees are randomly generated and overridden
--branch-scale SCALE — specify a value to scale all branch lengths 📏
--single-output — output all alignments into a single file
--write-all — enable outputting internal sequences
--seed NUM — random seed number (default: CPU clock). Be careful: to make AliSim reproducible, users should specify the seed number 🌱
-gz — enable output compression, but it takes longer running time 🐌
-af phy|fasta — set the output format (default: phylip)

User Manual is available at http://www.iqtree.org/doc/AliSim 📖

🌟 ANALYSIS WITH GENTRIUS ALGORITHM 🌟

--gentrius FILE — the file must contain either a single species-tree or a set of subtrees
-pr_ab_matrix FILE — presence-absence matrix of loci coverage
-s FILE — PHYLIP/FASTA/NEXUS/CLUSTAL/MSF alignment file(s)
-p FILE — NEXUS/RAxML partition file
-g_stop_t NUM — stop after NUM species-trees were generated, or use 0 to turn off this stopping rule. Default: 1MLN trees.
-g_stop_i NUM — stop after NUM intermediate trees were visited, or use 0 to turn off this stopping rule. Default: 10MLN trees.
-g_stop_h NUM — stop after NUM hours (CPU time), or use 0 to turn off this stopping rule. Default: 7 days.
-g_non_stop — turn off all stopping rules. Chaos! Go nuts 🏃‍♀️
-g_query FILE — species-trees to test for an identical set of subtrees
-g_print — write all generated species-trees. WARNING: there might be millions of trees! 😭
-g_print_lim NUM — limit on the number of species-trees to be written
-g_print_induced — write induced partition subtrees
-g_print_m — write the presence-absence matrix
-g_rm_leaves NUM — invoke reverse analysis for complex datasets

🦠 GENOMIC EPIDEMIOLOGICAL ANALYSIS 🦠

--pathogen — apply the CMAPLE tree search algorithm if sequence divergence is low, otherwise apply the IQ-TREE algorithm
--pathogen-force — apply the CMAPLE tree search algorithm no matter how divergent the sequences are
--alrt <num_rep> — specify the number of replicates to compute SH-aLRT
--sprta — compute SPRTA (DeMaio et al., 2024) branch supports
--sprta-zero-branch — compute SPRTA supports for zero-length branches
--sprta-other-places — output alternative SPRs and their SPRTA supports
-T <num_thread> — specify the number of threads used for computing branch supports (SH-aLRT or SPRTA) 🧵

⏳ TIME TREE RECONSTRUCTION ⏳

--date FILE — file containing dates of tips or ancestral nodes
--date TAXNAME — extract dates from taxon names after the last '|'
--date-tip STRING — tip dates as a real number or YYYY-MM-DD
--date-root STRING — root date as a real number or YYYY-MM-DD
--date-ci NUM — number of replicates to compute the confidence interval
--clock-sd NUM — std-dev for the lognormal relaxed clock (default: 0.2)
--date-no-outgroup — exclude the outgroup from the time tree
--date-outlier NUM — Z-score cutoff to remove outlier tips/nodes (e.g. 3)
--date-options ".." — extra options passing directly to LSD2
--dating STRING — dating method: LSD for least square dating (default)

okay bestie that's the whole thing, you're officially a phylogenetic icon now 👑 this was iqtree3-mpi version 3.1.1+dfsg, dropped in July 2026, and yes it's serving IQTREE3-MPI(1) energy the entire time 💖✨ go build that tree fr fr 🌳🫶

📦 where this page comes from

ubuntu stonking: iqtree3 3.1.1+dfsg-2build1 · GPL-2.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms