Command-line interface

salmon is invoked as salmon <command> [options]. Run salmon <command> --help for the authoritative, version-specific option list; this page summarizes the main commands and options.

salmon <command>

Commands:
  index       Build a salmon index from a transcriptome FASTA
  quant       Quantify transcript abundances from FASTQ reads (or a BAM)
  quantmerge  Merge a column across samples' quant files into a matrix
  debug-map   Diagnostic: per-read best-mapping detail
  alevin      Single-cell (removed; redirects to alevin-fry)

Global: -q/--quiet, -h/--help, -V/--version. --no-version-check is accepted for C++ compatibility and is a no-op (2.0 never checks for updates).

salmon index

Build a reusable index from one or more transcriptome FASTA files.

Option	Description
-t, --transcripts <FASTA>…	Transcript FASTA file(s). Required.
-i, --index <DIR>	Output index directory. Required.
-k, --kmerLen <N>	K-mer length (odd, ≤ 31 recommended). Default 31.
-m, --minimizerLen <N>	Minimizer length (0 = auto → 19 for the default k=31). Default 0.
-p, --threads <N>	Worker threads (0 = all cores). Default 0.
-d, --decoys <FILE>	File of decoy sequence names (one per line; decoy records must come last in the FASTA).
--keepDuplicates	Retain exact-duplicate transcript sequences instead of collapsing them.
-n, --no-clip	Don’t clip poly-A tails. By default a reference ending in ≥10 As has its trailing As trimmed (all-A references are dropped), matching pufferfish.
--gencode	GENCODE references: truncate each name at the first |.
--keepFixedFasta	Keep the cleaned (non-ACGT-replaced) reference FASTA.
--keepIntermediate	Keep intermediate compacted-dBG files.
--tmpdir <DIR>	Directory for build intermediates (cleaned FASTA + cDBG files). Defaults to the index dir.
--sshashTmpDir <DIR>	Directory for sshash’s external minimizer-sort scratch. Defaults to a sshash_tmp subdirectory of --tmpdir (or the index dir when --tmpdir is unset). Override to place the sort scratch on a separate/fast disk; it is created before the build and removed afterwards (kept with --keepIntermediate).
--ramLimit <GiB>	RAM ceiling for sshash’s external minimizer sort — the main build-time memory/disk trade-off. Default 8; a smaller value uses less RAM but spills to disk sooner.
--filterSize <N>	Accepted for compatibility; no effect.

salmon index -t transcripts.fa -i salmon_index -p 16

salmon quant

Quantify from FASTQ reads (reads mode, -i), from a transcriptome BAM (alignment mode, -a), or from a RAD file of mappings (RAD mode, --rad).

Inputs / outputs

Option	Description
-i, --index <DIR>	Salmon index (reads mode).
-a, --alignments <BAM>	Alignment mode: a name-grouped BAM of reads aligned to the transcriptome. With --annotation, a genome-aligned BAM instead (see below).
--annotation <GTF|GFF>	Genome-alignment mode: project a genome-aligned BAM into transcriptome coordinates via this annotation. See genome-alignment quantification.
--genome <FASTA>	Genome FASTA (genome mode); enables bias correction by reconstructing transcript sequences from exon slices.
--juncMissDiscount <f>	Penalty for an unannotated splice junction in genome projection (default 1.0 = none).
--rad <RAD>	RAD mode: quantify a RAD file of mappings (salmon --writeRad or piscem map-bulk/sketch output) directly. No -i needed — reference names travel in the RAD header. See RAD I/O & deterministic quantification.
--fldPolicy <baked|derive|prior>	--rad only: where the fragment-length distribution comes from. baked (default) reproduces the run that wrote the RAD; derive rebuilds it from the RAD; prior puts --fldMean/--fldSD in sole control. See RAD I/O & determinism.
-t, --targets <FASTA>	Transcriptome FASTA (alignment mode). Enables the error model in ordinary alignment mode; supplies reference sequences for bias correction and (with --errorModel) the deterministic error model.
-l, --libType <TYPE>	Library type (e.g. IU, ISR, A for auto). Default A. See library types.
-1/-2, --mates1/2 <FASTQ>…	Paired-end read files.
-r, --unmatedReads <FASTQ>…	Single-end read files.
-o, --output <DIR>	Output directory. Required.
-p, --threads <N>	Execution-slot budget (0 = all cores), shared between mapping and gzip decompression. On compressed input a live controller divides the budget from measurement; see threads and compressed input.
--decoder <MODE>	Gzip decoder for the reads: auto (default), serial, parallel, or parallel=N to pin N slots per decodable input. Decided per input file; a plain, FIFO, or otherwise non-seekable input falls back to serial by itself without affecting the others.
--threadPolicy <FILE>	JSON overriding when the parallel decoder engages (same format piscem uses). Unknown fields are an error, not a silent no-op.
-g, --geneMap <FILE>	Transcript-to-gene map (GTF/GFF or 2-column TSV); also writes quant.genes.sf. Read and validated before quantification starts. tximport is preferred; this option may be removed in a future release.
--ignoreTxVersion	Compare transcript identifiers without their trailing .N version suffix when joining --geneMap to quantified transcripts. Off by default. See Ensembl cDNA + GTF.

Threads and compressed input

-p names one budget of execution slots, not a mapping-thread count with decompression taken on top. When the reads are gzip and the parallel decoder is engaged, a live controller measures how much each side costs as the run proceeds and moves slots to whichever pays; totals in quant.sf and meta_info.json are unaffected by where the slots went.

Whether the parallel decoder engages at all defaults per mapping mode, from measurement — selective alignment does far more work per fragment than sketch, so decoding is worth dedicated slots much later:

mode	engages when -p ≥ (per gzip input)
selective alignment (± --deterministic)	50
sketch	10
sketch --deterministic	9

Below the threshold the serial decoder inflates inline on the mapping threads, which measured faster at every budget tested under it. Override with --decoder or --threadPolicy.

Input compression is detected from content, never file names, on every input path: gzip (including BGZF and multi-member), bzip2, xz and zstd all work for reads, targets, alignments and --geneMap — including a gzip file under a misleading name.

Mapping

Option	Description
--sketch	Alignment-free pseudoalignment path.
--sketchStrictOrphans	Strict orphan rule in sketch mode.
--allowDovetail	Admit dovetailed short-insert fragments.
--minScoreFraction <f>	Min alignment score as a fraction of perfect. Default 0.65.
--ma/--mp/--go/--ge	Match score / mismatch / gap-open / gap-extend.
--orphanChainSubThresh <f>	Orphan chain pruning (default 0.0 = align all).
--noErrorModel	Disable the alignment error model (ordinary alignment mode).
--errorModel	Opt in to the order-independent error model in deterministic alignment mode (-a --deterministic, needs -t). Off by default — deterministic mode scores by the BAM AS tag (single pass, at least as accurate against truth); this adds a second BAM pass. See deterministic alignment mode.

Model & bias

Option	Description
--seqBias	Sequence-specific bias correction.
--gcBias	Fragment-GC bias correction.
--posBias	Positional bias correction.
--noLengthCorrection	Use raw reference length (no effective-length correction).

RAD I/O & determinism

See the RAD I/O & deterministic quantification guide.

Option	Description
--writeRad <FILE>	Write per-fragment mappings to a RAD file (piscem map-bulk-compatible). Quantification still runs unless --skipQuant.
--skipQuant	Skip quantification (EM, Gibbs/bootstrap, quant.sf); still map, build equivalence classes, detect library type, write metadata.
--deterministic	Reproducible reads-mode quantification: map once to an intermediate RAD, then quantify from it with a fixed fragment-length distribution. Byte-identical across runs and thread counts.
--keepRad	Keep the --deterministic intermediate RAD (deleted by default).
--radCompress <CODEC>	RAD chunk compression for --writeRad / --deterministic: lz4 (default), zstd (smaller), or none.
--noCompressRad	Write uncompressed RAD chunks (overrides --radCompress).

Inference

Option	Description
--useEM	Standard EM instead of VBEM.
--meta	Metagenomic preset: plain EM, no range-factorized eq-classes, uniform init. Overrides --useEM/--rangeFactorizationBins.
--rangeFactorizationBins <N>	Range-factorization bins (0 disables). Default 4.
--numBootstraps <N>	Bootstrap replicates for posterior uncertainty.
--numGibbsSamples <N>	Gibbs posterior samples (mutually exclusive with bootstraps).
--thinningFactor <N>	Gibbs thinning factor. Default 16.
--incompatPrior <f>	Prior weight for strand-incompatible mappings. Default 0.

Diagnostics

Option	Description
--dumpEq / --dumpEqWeights	Dump equivalence classes (with weights).
--writeUnmappedNames	Write unmapped fragment names.
-z, --writeMappings <FILE>	Write per-mapping SAM records. --writeSam is an alias.
--writeBam <FILE>	Write the same per-mapping records as BGZF-compressed BAM. Mutually exclusive with --writeMappings/--writeSam; records for a fragment are contiguous, but no other order is imposed.
--bamCompressThreads <N>	BGZF compression workers for --writeBam. Defaults to about one per 3 mapping threads (at most 8), which balances compression against record production; see Record order.

salmon quant -i salmon_index -l A -1 r1.fq.gz -2 r2.fq.gz -p 16 -o out

Prefer tximport for gene-level estimates

tximport (R) and pytximport (Python) are the preferred way to obtain gene-level estimates from salmon output. They offer several ways to aggregate transcript abundances to the gene level, including one that computes an offset accounting for changes in average transcript length between samples — which shift a gene’s effective length even when its expression does not.

--geneMap aggregates within salmon instead, and salmon warns when it is used. The option may be removed in a future release.

Ensembl cDNA + GTF

Gene-level aggregation joins --geneMap entries to quantified transcripts by exact identifier. Ensembl spells the transcript version differently in its two files, so the reference human RNA-seq combination does not join as-is:

Source	Identifier
quant.sf, from an index built on the Ensembl cDNA FASTA	ENST00000622028.1
Ensembl GTF	transcript_id "ENST00000622028" + transcript_version "1"

Nothing matches. Each transcript then stands in as its own single-transcript gene, so quant.genes.sf is full-length but keyed by transcript: it is transcript-level output under a gene-level name, and no abundance is lost. salmon warns when the match rate is at or below 50%, says how many rows are stand-ins, reports how many transcripts would have matched, names the flag below, and lists every unmatched identifier in aux_info/genemap_unmatched_txps.json (removed when there are none):

{
  "unmatched_transcripts": [
    "ENST00000622028.1",
    "ENST00000456328.2"
  ]
}

Either pass --ignoreTxVersion, which compares identifiers without the trailing .N on both sides — the same semantics as tximport’s option of the same name — or use an annotation whose identifiers already carry versions (GENCODE’s FASTA and GTF agree, so it needs no flag):

salmon quant -i salmon_index -l A -1 r1.fq.gz -2 r2.fq.gz -o out \
  -g Homo_sapiens.GRCh38.115.gtf --ignoreTxVersion

It is off by default on purpose: rewriting identifiers implicitly would hide the next mismatch as effectively as this one was hidden.

salmon quantmerge

Merge a chosen column (e.g. NumReads or TPM) across multiple samples’ quant.sf files into a single matrix.

Note

Coming from C++ salmon? See what changed in 2.0 for removed, renamed, and accepted-but-ignored options.