Last update: Jun 28, 2024, Contributors: 95438353+HectorBanos, Diep Thi Hoang, Dominik Schrempf, Heiko Schmidt, Jana Trifinopoulos, Minh Bui, Thomaskf, Trongnhan Uit

Command reference

Commprehensive documentation of command-line options.

IQ-TREE is invoked from the command-line with e.g.:

iqtree -s <alignment> [OPTIONS]

assuming that IQ-TREE can be run by simply entering iqtree. If not, please change iqtree to the actual path of the executable or read the Quick start guide.

General options

General options are mainly intended for specifying input and output files:

Example usages:

• Reconstruct a maximum-likelihood tree given a sequence alignment file example.phy:

    iqtree -s example.phy
  

• Reconstruct a maximum-likelihood tree using at most 8 GB RAM and automatically detect the number of cores to use:

    # For version <= 1.5.X
    iqtree-omp -s example.phy -nt AUTO -mem 8G
      
    # For version >= 1.6.0, change iqtree-omp to just iqtree
    iqtree -s example.phy -nt AUTO -mem 8G
  

• Like above but write all output to myrun.* files:

    # For version <= 1.5.X
    iqtree-omp -s example.phy -nt AUTO -mem 8G -pre myrun
  
    # For version <= 1.6.0
    iqtree -s example.phy -nt AUTO -mem 8G -pre myrun
  

Checkpointing to resume stopped run

Starting with version 1.4.0 IQ-TREE supports checkpointing: If an IQ-TREE run was interrupted for some reason, rerunning it with the same command line and input data will automatically resume the analysis from the last stopped point. The previous log file will then be appended. If a run successfully finished, IQ-TREE will deny to rerun and issue an error message. A few options that control checkpointing behavior:

NOTE: IQ-TREE writes a checkpoint file with name suffix .ckp.gz in gzip format. Do not modify this file. If you delete this file, all checkpointing information will be lost!

Likelihood mapping analysis

Starting with version 1.4.0, IQ-TREE implements the likelihood mapping approach (Strimmer and von Haeseler, 1997) to assess the phylogenetic information of an input alignment. The detailed results will be printed to .iqtree report file. The likelihood mapping plots will be printed to .lmap.svg and .lmap.eps files.

Compared with the original implementation in TREE-PUZZLE, IQ-TREE is much faster and supports many more substitution models (including partition and mixture models).

TIP: The number of quartets specified via -lmap is recommended to be at least 25 times the number of sequences in the alignment, such that each sequence is covered ~100 times in the set of quartets drawn.

An example NEXUS cluster file (where A, B, C, etc. are sequence names):

#NEXUS
begin sets;
    taxset Cluster1 = A B C;
    taxset Cluster2 = D E;
    taxset Cluster3 = F G H I;
    taxset Cluster4 = J;
    taxset IGNORED = X;
end;

Here, Cluster1 to Cluster4 are four user-defined clusters of sequences. Note that users can give any names to the clusters instead of Cluster1, etc. If a cluster is named ignored or IGNORED the sequences included will be ignored in the likelihood mapping analysis.

If you provide a cluster file it has to contain between 1 and 4 clusters (plus an optional IGNORED or ignored cluster), which will tell IQ-TREE to perform an unclustered (default without a cluster file) or a clustered analysis with 2, 3 or 4 groups, respectively.

The names given to the clusters in the cluster file will be used to label the corners of the triangle diagrams.

Example usages:

• Perform solely likelihood mapping analysis (ignoring tree search) with 2000 quartets for an alignment example.phy with model being automatically selected:

    iqtree -s example.phy -lmap 2000 -n 0 -m TEST
  

You can now view the likelihood mapping plot file example.phy.lmap.svg, which looks like this:

It shows phylogenetic information of the alignment example.phy. On the top: distribution of quartets depicted by dots on the likelihood mapping plot. On the left: the three areas show support for one of the different groupings like (a,b)-(c,d). On the right: quartets falling into the three corners are informative. Those in three rectangles are partly informative and those in the center are uninformative. A good data set should have high number of informative quartets and low number of uninformative quartets. The meanings can also be found in the LIKELIHOOD MAPPING STATISTICS section of the report file example.phy.iqtree:

LIKELIHOOD MAPPING STATISTICS
-----------------------------

           (a,b)-(c,d)                              (a,b)-(c,d)      
                /\                                      /\           
               /  \                                    /  \          
              /    \                                  /  1 \         
             /  a1  \                                / \  / \        
            /\      /\                              /   \/   \       
           /  \    /  \                            /    /\    \      
          /    \  /    \                          / 6  /  \  4 \     
         /      \/      \                        /\   /  7 \   /\    
        /        |       \                      /  \ /______\ /  \   
       /   a3    |    a2  \                    / 3  |    5   |  2 \  
      /__________|_________\                  /_____|________|_____\ 
(a,d)-(b,c)            (a,c)-(b,d)      (a,d)-(b,c)            (a,c)-(b,d) 

Division of the likelihood mapping plots into 3 or 7 areas.
On the left the areas show support for one of the different groupings
like (a,b|c,d).
On the right the right quartets falling into the areas 1, 2 and 3 are
informative. Those in the rectangles 4, 5 and 6 are partly informative
and those in the center (7) are not informative.
.....

Automatic model selection

The default model (e.g., HKY+F for DNA, LG for protein data) may not fit well to the data. Therefore, IQ-TREE allows to automatically determine the best-fit model via a series of -m TEST... option:

TIP: During model section, IQ-TREE will write a model checkpoint file (suffix .model in version <= 1.5.X or .model.gz in version >= 1.6.X) that stores information of all models tested so far. Thus, if IQ-TREE is interrupted for whatever reason, restarting the run will load this file to reuse the computation.

IQ-TREE version 1.6 or later allows to additionally test Lie Markov DNA models by adding the following keyword to -m option:

When a partition file is specified then you can append MERGE keyword into -m option to find the best-fit partitioning scheme like PartitionFinder (Lanfear et al., 2012). More specifically,

WARNING: For versions <= 1.5.X, all commands with -m ...MERGE... will always perform an edge-unlinked partition scheme finding even if -spp option is used. Only in the next phase of tree reconstruction, then an edge-linked partition model is used. However, for versions 1.6.X onwards, the edge-linked partition finding is performed by -spp option.

Several parameters can be set to e.g. reduce computations:

NOTE: Some of the above options require a comma-separated list, which should not contain any empty space!

Example usages:

• Select best-fit model for alignment data.phy based on Bayesian information criterion (BIC):

    iqtree -s data.phy -m TESTONLY
  

• Select best-fit model for a protein alignment prot.phy using the new testing procedure and only consider WAG, LG and JTT matrix to save time:

    iqtree -s prot.phy -m MF -mset WAG,LG,JTT
  

• Find the best partitioning scheme for alignment data.phy and partition file partition.nex with a relaxed clustering at 10% to save time:

    iqtree -s data.phy -spp partition.nex -m TESTMERGEONLY -rcluster 10
  

Specifying substitution models

-m is a powerful option to specify substitution models, state frequency and rate heterogeneity type. The general syntax is:

-m MODEL+FreqType+RateType

where MODEL is a model name, +FreqType (optional) is the frequency type and +RateType (optional) is the rate heterogeneity type.

The following MODELs are available:

The following FreqTypes are supported:

Further options:

Example usages:

• Infer an ML tree for a DNA alignment dna.phy under GTR+I+G model:

    iqtree -s dna.phy -m GTR+I+G
  

• Infer an ML tree for a protein alignment prot.phy under LG+F+G model:

    iqtree -s prot.phy -m LG+F+G
  

• Infer an ML tree for a protein alignment prot.phy under profile mixture model LG+C10+F+G:

    iqtree -s prot.phy -m LG+C10+F+G
  

Example usages:

• Estimate linked exchangeabilities for a protein alignment prot.phy under C60+G model and a guide tree guide.treefile, where optimization is initialized from LG exchangeabilities

    iqtree -s prot.phy -m GTR20+C60+G --link-exchange --init-exchange LG -te guide.treefile
  

NOTE: For better and faster performance, read the recommendations provided in the Estimating amino acid substitution models section.

Rate heterogeneity

The following RateTypes are supported:

See Rate heterogeneity across sites for more details.

Further options:

Optionally, one can specify Ascertainment bias correction by appending +ASC to the model string. Advanced mixture models can also be specified via MIX{...} and FMIX{...} syntax. Option -mwopt can be used to turn on optimizing weights of mixture models.

Partition model options

Partition models are used for phylogenomic data with multiple genes. You first have to prepare a partition file in NEXUS or RAxML-style format. Then use the following options to input the partition file:

Site-specific frequency model options

The site-specific frequency model is used to substantially reduce the time and memory requirement compared with full profile mixture models C10 to C60. For full details see site-specific frequency model. To use this model you have to specify a profile mixture model with e.g. -m LG+C20+F+G together with a guide tree or a site frequency file:

With -fs option you can input a file containing your own site frequency profiles. The format of this file is that each line contains the site ID (starting from 1) and the state frequencies (20 for amino-acid) separated by white space. So it has as many lines as the number of sites in the alignment. The order of amino-acids is:

 A   R   N   D   C   Q   E   G   H   I   L   K   M   F   P   S   T   W   Y   V

Tree search parameters

The new IQ-TREE search algorithm (Nguyen et al., 2015) has several parameters that can be changed with:

NOTE: While the default parameters were empirically determined to work well under our extensive benchmark (Nguyen et al., 2015), it might not hold true for all data sets. If in doubt that tree search is still stuck in local optima, one should repeat analysis with at least 10 IQ-TREE runs. Moreover, our experience showed that -pers and -nstop are the most relevant options to change in such case. For example, data sets with many short sequences should be analyzed with smaller perturbation strength (e.g. -pers 0.2) and larger number of stop iterations (e.g. -nstop 500).

Example usages:

• Infer an ML tree for an alignment data.phy with increased stopping iteration of 500 and reduced perturbation strength of 0.2:

    iqtree -s data.phy -m TEST -nstop 500 -pers 0.2
  

• Infer an ML tree for an alignment data.phy obeying a topological constraint tree constraint.tree:

    iqtree -s data.phy -m TEST -g constraint.tree
  

Tree search for pathogen data

For pathogen data such as SARS-CoV-2 virus alignments, version 2.3.4.cmaple implements the MAPLE algorithm (De Maio et al., 2023) that performs tree search very quickly by exploiting the low divergent property of the sequences (i.e., sequences in the alignment are very similar to each other).

Example usages:

• Infer a maximum-likelihood tree for an alignment, automatically switching to CMAPLE algorithm if sequence divergence is low:

    iqtree2 -s data.phy --pathogen --prefix pathogen
  

It will print two output files:

• pathogen.treefile: The best approximate maximum-likelihood tree in NEWICK format.
• pathogen.log: The log file.

If you want to do other analyses on this tree and thus saving the tree search time, add -te pathogen.treefile to the command line of a subsequent IQ-TREE run to fix this tree topology and remove --pathogen option to invoke the default IQ-TREE machinery.

• Infer a tree like above and additionally assign branch supports using SH-aLRT test with 1000 replicates using 4 CPU cores:

    iqtree2 -s data.phy --pathogen --alrt 1000 -T 4 --prefix pathogen
  

The tree pathogen.treefile will contain branch supports for all internal branches.

Ultrafast bootstrap parameters

The ultrafast bootstrap (UFBoot) approximation (Minh et al., 2013; Hoang et al., in press) has several parameters that can be changed with:

Example usages:

• Select best-fit model, infer an ML tree and perform ultrafast bootstrap with 1000 replicates:

    iqtree -s data.phy -m TEST -bb 1000
  

• Reconstruct ML and perform ultrafast bootstrap (5000 replicates) under a partition model file partition.nex:

    iqtree -s data.phy -spp partition.nex -m TEST -bb 5000
  

Nonparametric bootstrap

The slow standard nonparametric bootstrap (Felsenstein, 1985) can be run with:

Single branch tests

The following single branch tests are faster than all bootstrap analysis and recommended for extremely large data sets (e.g., >10,000 taxa):

TIP: One can combine all these tests (also including UFBoot -bb option) within a single IQ-TREE run. Each branch in the resulting tree will be assigned several support values separated by slash (/), where the order of support values is stated in the .iqtree report file.

Example usages:

• Infer an ML tree and perform SH-aLRT test as well as ultrafast bootstrap with 1000 replicates:

    iqtree -s data.phy -m TEST -alrt 1000 -bb 1000
  

Ancestral sequence reconstruction

This feature is newly introduced in version 1.6. You can combine this feature with -te option to determine ancestral sequences along a user-defined tree (Otherwise, IQ-TREE computes ancestral sequences of the ML tree).

Example usages:

iqtree -s example.phy -m JC+G -asr

The first few lines of the output file example.phy.state may look like this:

# Ancestral state reconstruction for all nodes in example.phy.treefile
# This file can be read in MS Excel or in R with command:
#   tab=read.table('example.phy.state',header=TRUE)
# Columns are tab-separated with following meaning:
#   Node:  Node name in the tree
#   Site:  Alignment site ID
#   State: Most likely state assignment
#   p_X:   Posterior probability for state X (empirical Bayesian method)
Node    Site    State   p_A     p_C     p_G     p_T
Node2   1       C       0.00004 0.99992 0.00002 0.00002
Node2   2       A       0.92378 0.00578 0.00577 0.06468
Node2   3       A       0.95469 0.02634 0.00675 0.01222
Node2   4       C       0.00002 0.99992 0.00002 0.00004
...

Tree topology tests

IQ-TREE provides a number of tests for significant topological differences between trees. The AU test implementation in IQ-TREE is much more efficient than the original CONSEL by supporting SSE, AVX and multicore parallelization. Moreover, it is more appropriate than CONSEL for partition analysis by bootstrap resampling sites within partitions, whereas CONSEL is not partition-aware.

NOTE: There is a discrepancy between IQ-TREE and CONSEL for the AU test: IQ-TREE implements the least-square estimate for p-values whereas CONSEL provides the maximum-likelihood estimate (MLE) for p-values. Hence, the AU p-values might be slightly different. We plan to implement MLE for AU p-values in IQ-TREE soon.

Example usages:

• Given alignment data.phy, test a set of trees in data.trees using AU test with 10,000 replicates:

    iqtree -s data.phy -m GTR+G -n 0 -z data.trees -zb 10000 -au 
  

• Same above but for a partitioned data partition.nex and additionally performing weighted test:

    iqtree -s data.phy -spp partition.nex -n 0 -z data.trees -zb 10000 -au -zw
  

Constructing consensus tree

IQ-TREE provides a fast implementation of consensus tree construction for post analysis:

Computing Robinson-Foulds distance

IQ-TREE provides a fast implementation of Robinson-Foulds (RF) distance computation between trees:

Example usages:

• Compute the pairwise RF distances between 2 sets of trees:

    iqtree -rf tree_set1 tree_set2
  

• Compute the all-to-all RF distances within a set of trees:

    iqtree -rf_all tree_set
  

Generating random trees

IQ-TREE provides several random tree generation models:

Example usages:

• Generate a 100-taxon random tree into the file 100.tree under the Yule Harding model:

    iqtree -r 100 100.tree 
  

• Generate 100-taxon random tree with mean branch lengths of 0.2 and branch lengths are between 0.05 and 0.3:

    iqtree -r 100 -rlen 0.05 0.2 0.3 100.tree 
  

• Generate a random tree under uniform model:

    iqtree -ru 100 100.tree 
  

• Generate a random tree where taxon labels follow an alignment:

    iqtree -s example.phy -r 17 example.random.tree 
  

Note that, you still need to specify the -r option being equal to the number of taxa in the alignment.

Miscellaneous options

Example usages:

• Print alignment information about parsimony informative sites:

    iqtree -s example.phy -m JC -n 0 -alninfo
  

The first few lines of the output file example.phy.alninfo may look like this:

# Alignment site statistics
# This file can be read in MS Excel or in R with command:
#   tab=read.table('example.phy.alninfo',header=TRUE)
# Columns are tab-separated with following meaning:
#   Site:   Site ID
#   Stat:   Statistic, I=informative, C=constant, c=constant+ambiguous,
#           U=Uninformative but not constant, -=all-gaps
Site    Stat
1       U
2       I
3       I
4       U
5       U

• Print site log-likelihood and posterior probability for each Gamma rate category:

    iqtree -s example.phy -m JC+G -wspr -wslr  -n 0
  

The first few lines of the output file example.phy.siteprob (printed by -wspr option) may look like this:

Site    p1      p2      p3      p4
1       0.180497        0.534405        0.281   0.00409816
2       4.73239e-05     0.0373409       0.557705        0.404907
3       1.23186e-08     0.000426294     0.0672021       0.932372
4       0.180497        0.534405        0.281   0.00409816
5       0.180497        0.534405        0.281   0.00409816

where pX is the probability of the site falling into rate category X.

The first few lines of the output file example.phy.sitelh (printed by -wslr option) may look like this:

# Site likelihood per rate/mixture category
# This file can be read in MS Excel or in R with command:
#   tab=read.table('example.phy.sitelh',header=TRUE,fill=TRUE)
# Columns are tab-separated with following meaning:
#   Site:   Alignment site ID
#   LnL:    Logarithm of site likelihood
#           Thus, sum of LnL is equal to tree log-likelihood
#   LnLW_k: Logarithm of (category-k site likelihood times category-k weight)
#           Thus, sum of exp(LnLW_k) is equal to exp(LnL)
Site    LnL     LnLW_1  LnLW_2  LnLW_3  LnLW_4
1       -7.0432 -8.7552 -7.6698 -8.3126 -12.5404
2       -17.5900        -27.5485        -20.8776        -18.1739        -18.4941
3       -20.3313        -38.5435        -28.0917        -23.0314        -20.4014
4       -7.0432 -8.7552 -7.6698 -8.3126 -12.5404
5       -7.0432 -8.7552 -7.6698 -8.3126 -12.5404