Migrating from C++ salmon (≤ 1.12.0) to salmon 2.0 (Rust)

salmon 2.0 is a from-scratch Rust rewrite. It keeps the same core workflow (salmon index → salmon quant → quant.sf) and the same output formats that downstream tools consume, but it is a new major version and makes some breaking changes. This guide maps C++ options/behavior to 2.0.

Breaking change: rebuild your index

2.0 uses a new index format and cannot read C++ (pufferfish) indices. Rebuild with salmon index from 2.0; loading a C++ index (or pointing C++ salmon at a 2.0 index) is detected and rejected with a clear error.

quant.sf is unchanged (drop-in for tximport/tximeta). Inferential replicates (aux_info/bootstrap/{names.tsv.gz,bootstraps.gz} for both --numBootstraps and --numGibbsSamples) are written in the same format C++ salmon used, so tximport/fishpond/swish keep working. The bias-model diagnostic dumps in aux_info/ (obs/exp*_seq.gz, obs/exp_gc.gz, obs/exp*_pos.gz, fld.gz) are in a documented Rust format (see the docs site); they are not consumed by the standard downstream R packages.

Removed subcommands

C++	2.0
salmon alevin	Removed. Use the alevin-fry ecosystem for single-cell. salmon alevin … prints this redirect and exits.

Removed options (produce an error + this note)

Passing any of these errors out with a pointer to this guide. They are gone because the underlying feature was removed or has no equivalent in 2.0.

Option	Subcommand	Why / alternative
--features	index	Index-feature dump not supported by the cf1-rs/piscem-rs index builder.
--mimicBT2, --mimicStrictBT2	quant	bowtie2-mimicking presets removed; 2.0's selective alignment is the single supported mode.
--minAssignedFrags	quant	The "zero the output below N assigned fragments" guard was removed; 2.0 reports what it quantifies.
--alternativeInitMode, --bootstrapReproject, --noGammaDraw	quant	Inference-internal toggles not present in the 2.0 optimizer/Gibbs implementation.
--numBiasSamples	quant	2.0 collects bias samples online (abundance-aware dual-phase), so a fixed sample budget no longer applies.
--auxTargetFile, --writeOrphanLinks	quant -a	Removed alignment-mode features.

Accepted but ignored (parse + warn)

These still parse so existing scripts run; 2.0 logs a warning and ignores them (the behavior is either the default now or handled differently).

• global: --no-version-check (and the SALMON_NO_VERSION_CHECK environment variable) — accepted before or after the command (e.g. salmon --no-version-check quant …), matching C++. It is a silent no-op: 2.0 never contacts the network to check for a newer release.
• index: --filterSize
• quant: --eqclasses, --noFragLengthDist, --noSingleFragProb, --mismatchSeedSkip, --disableChainingHeuristic, --hitFilterPolicy, --maxRecoverReadOcc, --validateMappings (selective alignment is the default)
• quant -a: --mappingCacheMemoryLimit, -s/--sampleOut, -u/--sampleUnaligned, --writeQualities

New in 2.0

• --sketch — alignment-free pseudoalignment mode (faster; quantifies directly from k-mer/equivalence-class hits).
• --sketchStrictOrphans — in --sketch, only orphan a pair when the other mate had no matching k-mers (the conservative rule). Default is the relaxed rule (orphan when the other mate has no consistent target), which tracks selective alignment more closely.
• --allowDovetail — now honored in --sketch as well (admits dovetailed short-insert fragments).

Behavior differences to be aware of

• Sketch orphan rule defaults to the relaxed policy (see --sketchStrictOrphans).
• Selective-alignment chain pruning: 2.0 currently defaults --orphanChainSubThresh and --postMergeChainSubThresh to 0.0 (off) — it aligns every candidate, which is marginally more sensitive than C++ (which uses 0.95/0.9). Quantification is essentially unaffected (per-transcript Pearson ≈ 0.999); pass --orphanChainSubThresh 0.95 --postMergeChainSubThresh 0.9 to reproduce C++ mapping counts exactly. See docs/mapping-parity-differences.md.

Unchanged

Index/quant basics, quant.sf, cmd_info.json, lib_format_counts.json, aux_info/meta_info.json, --libType/-l, --threads/-p, -k/--kmerLen, -m/--minimizerLen, -n/--no-clip (poly-A clipping, on by default), --seqBias, --gcBias, --posBias, --numBootstraps, --numGibbsSamples, --useEM, --meta (metagenomic preset), --dumpEq, -g/--geneMap, decoys, and salmon quantmerge.