place

The place command places the genomes of one alignment file on one reference package and writes a jplace file. It computes exactly what GTDB-Tk’s pplacer -m WAG -j <cpus> -c <refpkg> -o <out.json> <msa> computes: the same placements and the same numbers.

gplace place --msa_file user_msa_file.fasta --refpkg gtdbtk.package.2.refpkg \
             --out_file gplace.jplace --cpus 40

The options you will usually need

Option	What it does
`--msa_file`	The alignment of your genomes (FASTA), e.g. GTDB-Tk’s `user_msa_file.fasta`.
`--refpkg`	The reference package (a `.refpkg` folder), e.g. `gtdbtk.package.2.refpkg`.
`--out_file`	The jplace file to write.
`--cpus`	Number of worker processes, or `auto` to pick a good number for this computer.
`--max_memory`	Memory gPlace may use, e.g. `64G`. Needed for large trees such as the full GTDB bacterial tree; the result is the same. See Large trees and memory limits.

More options

Everything else is for special cases, and each option keeps pplacer’s default:

Large trees and memory limits: tile size, memory estimates, many queries in one run.
pplacer’s options: pplacer’s search settings, pre-masking, Stockholm query files, taxonomic classification, and reference files instead of a reference package (pplacer’s -t/-r/-s).
Using your own tree: trees fitted with IQ-TREE or RAxML-NG, including --full_model.
Models: the evolutionary models, and --fix_gamma_underflow.

A pplacer command line can be reused as it is: gPlace also accepts pplacer’s spelling of every option (-c for --refpkg, -o for --out_file, --keep-at-most for --keep_at_most, …).

Files output

jplace file (--out_file)
gplace.log (next to the jplace file)

Example

gplace place --msa_file user_msa_file.fasta --refpkg mini.refpkg --out_file gplace.jplace --cpus 4

[2026-10-01 19:23:40] INFO: gPlace v0.1.0
[2026-10-01 19:23:40] INFO: gplace place --msa_file user_msa_file.fasta --refpkg mini.refpkg --out_file gplace.jplace --cpus 4
[2026-10-01 19:23:42] INFO: Read 20 sequences from user_msa_file.fasta
[2026-10-01 19:23:44] INFO: Model: WAG + CAT (20 rates), model frequencies (protein)
[2026-10-01 19:23:44] INFO: Placing 20 queries on mini.refpkg (493 nodes, 4,891 sites, 4 CPUs; estimated peak memory 0.9 GiB).
[2026-10-01 19:23:47] INFO: Cached likelihood vectors for 246 internal nodes (0.4 GB).
[2026-10-01 19:23:48] INFO: Scored 20 queries against 492 edges.
[2026-10-01 19:23:51] INFO: Wrote 20 placements to gplace.jplace (8.0 s).

On the full GTDB bacterial tree within a 64 GB job:

gplace place --msa_file gtdbtk.bac120.user_msa.fasta --refpkg release226/pplacer/gtdb_r226_bac120.refpkg \
    --out_file gplace.jplace --cpus 40 --max_memory 64G

All options

usage: gplace place --msa_file MSA_FILE --out_file OUT_FILE [--refpkg REFPKG]
                    [--cpus CPUS] [--fix_gamma_underflow] [--mrca_class]
                    [--discard_nonoverlapped] [--ranked_edges N]
                    [--tmpdir TMPDIR] [-h]
                    [--tile_edges TILE_EDGES | --max_memory MAX_MEMORY]
                    [--ml_tolerance FLOAT] [--start_pend FLOAT]
                    [--max_pend FLOAT] [--max_strikes INT]
                    [--strike_box FLOAT] [--max_pitches INT]
                    [--keep_at_most INT] [--keep_factor FLOAT] [--no_pre_mask]
                    [--always_refine] [--tree TREE] [--ref_aln REF_ALN]
                    [--stats STATS] [--ref_dir REF_DIR]
                    [--full_model [MODEL_FILE]] [--model MODEL]
                    [--model_freqs] [--gamma_cats INT] [--gamma_alpha FLOAT]

required named arguments

--msa_file: aligned query sequences, protein or DNA as the reference: FASTA, or Stockholm if the name ends in .sto or .sth (.gz: gzipped) as in pplacer (e.g. GTDB-Tk user_msa_file.fasta for one class-level tree)
--out_file: output jplace file (same content as pplacer’s -o file)

reference (–refpkg, or –tree with the files below)

--refpkg: pplacer reference package directory (e.g. gtdbtk.package.N.refpkg)

optional arguments

--cpus

number of CPUs to use, or “auto”: the value saved by gplace benchmark on this machine, otherwise measured during the run (placement is memory-bandwidth bound, so the fastest value is often below the CPU count)

Default: '1'

--fix_gamma_underflow

gamma-model reference packages only: avoid pplacer’s rescaling underflow, which gives likelihood -inf on large trees. Results then differ from pplacer (slightly where pplacer is finite). Default: reproduce pplacer exactly

--mrca_class, --mrca-class

reference packages with a taxonomy: classify each placement by the taxonomic MRCA of the reference sequences below its edge, instead of by edge painting (pplacer’s –mrca-class)

--discard_nonoverlapped, --discard-nonoverlapped

drop queries that have no residue in any column where a reference sequence has one, instead of stopping (pplacer’s –discard-nonoverlapped)

--ranked_edges

untiled placement: keep only each query’s first N edges of pplacer’s ranking (164 covers pplacer’s default search) instead of its prefilter score for every edge, scoring queries in batches of 20,000. Memory then barely grows with the number of queries; results are identical (a query that needs more edges is ranked again in full). Tiled placement always works this way. Default: keep every score

--tmpdir

specify alternative directory for temporary files

Default: '/tmp'

mutually exclusive optional arguments

--tile_edges: place tile by tile, holding one tile of at most this many edges in memory at a time (exact; for reference trees too large for memory, such as the full GTDB bacterial tree). Default: no tiling
--max_memory: memory gPlace may use, e.g. 64G or 500M (a plain number is GiB). If the estimated peak fits, gPlace places without tiles; otherwise it picks the largest tile size that fits, from the reference tree and the number of queries (chosen separately for each reference package)

pplacer settings (default: pplacer’s; results stay identical to pplacer run with the same settings)

--ml_tolerance, --ml-tolerance

tolerance of the first-stage branch length optimisation (the kept placements are refined to 1e-5)

Default: 0.01

--start_pend, --start-pend

starting pendant branch length

Default: 0.1

--max_pend, --max-pend

maximum pendant branch length

Default: 2.0

--max_strikes, --max-strikes

stop trying edges after this many strikes (edges more than strike_box below the best so far); 0 tries every edge of the tree

Default: 6

--strike_box, --strike-box

size of the strike box in log-likelihood units

Default: 3.0

--max_pitches, --max-pitches

try at most this many edges (plus one) per query

Default: 40

--keep_at_most, --keep-at-most

maximum number of placements kept per query

Default: 7

--keep_factor, --keep-factor

keep placements whose likelihood is at least this fraction of the best one’s

Default: 0.01

--no_pre_mask, --no-pre-mask

do not pre-mask: keep every alignment column (query residues where no reference has one then count), do not check that queries overlap the reference sequences, and merge only queries with identical whole sequences into one record

--always_refine, --always-refine

refine the model before placing: CAT models get new site rate categories on the reference tree (pplacer always does this when the query alignment holds the reference sequences); no effect on gamma models

reference files (instead of, or replacing those of, –refpkg; pplacer’s -t/-r/-s/-d)

--tree, -t: reference tree (Newick)
--ref_aln, -r: reference alignment (FASTA). Without it (and without –refpkg) the query alignment must contain every reference sequence
--stats, -s: model: a RAxML 7 info file, a PhyML 3.0 stats file or a JSON model file (as pplacer reads them; gamma rates). A –refpkg phylo_model takes precedence
--ref_dir, -d: directory containing the –tree, –ref_aln and –stats files
--full_model: place with the complete model of an IQ-TREE or RAxML-NG fit instead of the part pplacer reads (results then differ from pplacer). MODEL_FILE: IQ-TREE’s <prefix>.ckp.gz (its <prefix>.iqtree is read too) or RAxML-NG’s <prefix>.raxml.bestModel (its <prefix>.raxml.log is read too); without it, the file next to the –stats .iqtree file or RAxML-NG log

model settings (pplacer’s; used only for what a –stats file does not set)

--model, -m

substitution model name. pplacer v1.1.alpha19 always takes it from the statistics file or the reference package, so this has no effect (accepted for pplacer command lines)

Default: 'LG'

--model_freqs, --model-freqs

protein models from a –stats file: the model’s amino acid frequencies instead of the reference alignment’s

--gamma_cats, --gamma-cats

gamma categories, when the –stats file gives none (PhyML without gamma, JSON with a null ras_model)

Default: 1

--gamma_alpha, --gamma-alpha

gamma shape parameter, when the –stats file gives none

Default: 1.0