---
title: Command-line interface
description: salmon 2.0 subcommands and their key options.
---

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 `A`s has its trailing `A`s 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.* |

```sh
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](../../guides/genome-projection/). |
| `--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](../../guides/rad-and-determinism/). |
| `--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](../../guides/rad-and-determinism/#fragment-length-distribution---fldpolicy). |
| `-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](../../guides/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](#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](#prefer-tximport-for-gene-level-estimates); 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](#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](../../guides/rad-and-determinism/#deterministic-alignment-mode--a---deterministic). |

### 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](../../guides/rad-and-determinism/) 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](../output-formats/#record-order). |

```sh
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](https://bioconductor.org/packages/tximport/) (R) and
[pytximport](https://pytximport.readthedocs.io/) (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):

```json
{
  "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):

```sh
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](../../migrating/from-cpp/) for
removed, renamed, and accepted-but-ignored options.
:::
