IQTREE2(1)

📦
version 2.4.0 · 5 versions
, in ubuntu stonking

🌈 IQTREE2 🌈 — User Commands (bestie edition, part 1)

okay so this is the manual page for iqtree2, and I'm gonna walk you through every single flag like we're texting at 2am. it's long. it's got ✨range✨. grab a snack. 🍓

🎀 NAME 🎀

iqtree2 — efficient phylogenetic software by maximum likelihood.

that's it. that's the whole name section. she's efficient, she's phylogenetic, she's software, and she does it by maximum likelihood. periodt. 💅

💖 SYNOPSIS 💖

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

the ... is doing a LOT of heavy lifting there but we love her for it. 🙈

🦋 DESCRIPTION 🦋

IQ-TREE multicore version 2.4.0 for Linux x86 64-bit built Jul 28 2026

Developed by Bui Quang Minh, Nguyen Lam Tung, Olga Chernomor, Heiko Schmidt, Dominik Schrempf, Michael Woodhams, Ly Trong Nhan, Thomas Wong

hand on heart for the dev team, no cap, they ate 🫶

🌟 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)
  • -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)

lowkey this whole block is your starter pack. -s is how you hand her an alignment, -T is how you get her to actually use your cores, and --quiet is for when you want zero screen noise. 💜

⏱️ 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)

so if you changed your mind mid-run, this is your rewind button. iconic behaviour honestly. 🎀

🧩 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

the way that -p, -q, -Q and -S are all siblings but with completely different vibes... choose wisely bestie. 🌸

🔍 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 (defaut: 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

this is the main character section and I need you to respect it. --allnni? that's the "go harder" button. --fast? that's the "I have 4 minutes before my meeting" button. --tree-fix? that's the "bestie do NOT move a single branch" button. 🔥

🚀 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

-B is the signature move of IQ-TREE, iykyk. and remember, -B and -J want at least 1000 replicates, that's not a suggestion, that's the law. 👑

🎲 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

yes, --jack-prop shows up in two different sections and yes, that's just how she is. we don't question it. same (default: 0.5) both times, so you're safe either way. ✨

🧪 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
heads up: --alrt 0 is literally the number zero, and that's what unlocks the parametric aLRT test. zero is not nothing here. 💀

🕵️ MODEL-FINDER 🕵️

  • -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)
  • --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)

-m MFP is THE girl. model selection and tree inference in one breath? obsessed. 🧚

🧵 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)

note that --merge-model and --merge-rate each pull double duty — one form takes 1|all, the other takes a comma-separated list. don't mix them up bestie. 🙈

🧬 SUBSTITUTION MODEL 🧬

  • -m STRING — Model name string (e.g. GTR+F+I+G)

and now, the menu. every flavour she's got:

  • 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

the Lie Markov list alone is a whole mood board. and if none of these serve, you can literally hand her a file with your own model parameters. she said "bring your own, I'll rate it". 😭

📊 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

just tack these onto your -m string and she'll adjust her whole frequency situation for you. the abcd one is giving very specific. 💅

📈 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 Gamma model with n categories
  • -m ...+R[n] — FreeRate model with n categories (default n=4)
  • -m ...*R[n] — FreeRate model with unlinked model parameters
  • -m ...+I+R[n] — Invariable sites plus FreeRate model with n categories
  • -m ...+Hn — Heterotachy model with n classes

mini pop quiz bestie: +G uses a plus, *G uses a star, and that one character is the difference between linked and unlinked model parameters. same deal for +R vs *R. don't fumble it. 🌟

  • -m ...*Hn — the heterotachy model 🌀 with n classes and unlinked parameters (each class is doing its own thing, main character energy, no shared vibes).
  • --alpha-min NUM — the minimum Gamma shape parameter for site rates (default: 0.02).
  • --gamma-median — use the median approximation for +G site rates instead of the default mean ✨.
  • --rate — write the empirical Bayesian site rates out to the .rate file.
  • --mlrate — write the maximum likelihood site rates out to the .mlrate file.

🧬 POLYMORPHISM AWARE MODELS (PoMo) 🧬

  • -s FILE — the input counts file (check the manual for this one, bestie 👀).
  • -m ...+P — the DNA substitution model (the ones from up above ☝️) used together with PoMo.
  • -m ...+N<POPSIZE> — the 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}" — a mixture model with K components.
  • -m "FMIX{f1,...fK}" — a frequency mixture model with K components.
  • --mix-opt — optimize the mixture weights (default: detect).
  • -m ...+ASC — ascertainment bias correction.
  • --tree-freq FILE — the input tree used to infer the site frequency model.
  • --site-freq FILE — the input site frequency model file.
  • --freq-max — posterior maximum instead of the mean approximation.

🔍 TREE TOPOLOGY TEST 🔍

  • --trees FILE — the set of trees whose log-likelihoods you want evaluated.
  • --test NUM — how many replicates to run for the topology test.
  • --test-weight — go ahead and do the weighted KH and SH tests.
  • --test-au — the approximately unbiased (AU) test (Shimodaira 2002).
  • --sitelh — write the site log-likelihoods to the .sitelh file.

👵 ANCESTRAL STATE RECONSTRUCTION 👵

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

⚖️ TEST OF SYMMETRY ⚖️

  • --symtest — perform three tests of symmetry.
  • --symtest-only — do --symtest and then exist. (Yes, the page literally says exist. We are not touching it 💀)
  • --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 — the P-value cutoff (default: 0.05).
  • --symtest-keep-zero — keep the NAs in the tests.

🧮 CONCORDANCE FACTOR ANALYSIS 🧮

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

🧪 ALISIM: ALIGNMENT SIMULATOR 🧪

Usage, gorgeous:

iqtree --alisim <OUTPUT_PREFIX> [-m MODEL] [-t TREE] ...
  • --alisim OUTPUT_ALIGNMENT — activate AliSim and tell it 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 how many output datasets you want.
  • --seqtype STRING — BIN, DNA, AA, CODON, MORPH{NUM_STATES} (default: auto-detect). For morphological data, 0<NUM_STATES<=32.
  • --m MODEL_STRING — pick the evolutionary model. See the Manual for more detail.
  • --mdef FILE — the name of a NEXUS model file that defines new models (see Manual).
  • --fundi TAXA_LIST,RHO — specify a list of taxa, and Rho (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 — turn on the feature that simulates a substitution-level mixture model.
  • --no-unaligned — stop outputting a file of unaligned sequences when you're using indel models.
  • --root-seq FILE,SEQ_NAME — specify the root sequence from an alignment.
  • -s FILE — specify the input sequence alignment.
  • --no-copy-gaps — disable 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 so it can 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 — hand over a definition file of distributions, which can 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 that scales all branch lengths.
  • --single-output — output all the alignments into one single file.
  • --write-all — enable outputting internal sequences.
  • --seed NUM — the random seed number (default: CPU clock). ⚠️ Be careful to make AliSim reproducible, you should specify the seed number.
  • -gz — enable output compression, but it takes longer to run.
  • -af phy|fasta — set the output format (default: phylip).

The 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 — the 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 this stopping rule off. Default: 1MLN trees.
  • -g_stop_i NUM — stop after NUM intermediate trees were visited, or use 0 to turn this stopping rule off. Default: 10MLN trees.
  • -g_stop_h NUM — stop after NUM hours (CPU time), or use 0 to turn this stopping rule off. Default: 7 days.
  • -g_non_stop — turn off all the stopping rules, live your truth.
  • -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! Millions. Of trees, bestie. Millions!! 😭
  • -g_print_lim NUM — a 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 regardless of sequence divergence.

⏳ TIME TREE RECONSTRUCTION ⏳

  • --date FILE — the 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).

And that's the whole page, angel 🫶 go sequence something iconic. This beauty is iqtree2 2.4.0+dfsg, dated July 2026, and it lives in section IQTREE2(1) of the manual. Slay 💅✨

📦 where this page comes from