Running Cell Ranger

December 19, 2025 · 4 min read · Analysis Notes

TL;DR: Complete guide to installing and running Cell Ranger for 10x Genomics single-cell RNA-seq data analysis. Covers installation, reference setup, FASTQ processing, and both count and multi pipelines for standard and multiplexed experiments.

Platform Note: Cell Ranger runs on Linux-like systems and does not provide native support for MacOS or Windows. For Mac users, consider salmon/alevin, kallisto/bustools, or STARsolo (which produces nearly identical output to Cell Ranger 4.x).

Cell Ranger Workflow

Prerequisites

Linux server with sufficient RAM (64GB+ recommended)
Root or sudo access for installation
10x Genomics scRNA-seq FASTQ files

1. Installation

Download and install the latest Cell Ranger version from 10x Genomics downloads:

# Navigate to install directory
cd $HOME

# Download pre-compiled binary (v8.0.1 example)
curl -o cellranger-8.0.1.tar.gz "https://cf.10xgenomics.com/releases/cell-exp/cellranger-8.0.1.tar.gz?Expires=1721274397&Key-Pair-Id=APKAI7S6A5RYOXBWRPDA&Signature=Wlo3LN3WMS52GnZDbPSo3rPiRzKxt7wlMo3cezn3HPyxH~WwyIKV8iXyVbHLJZtRnA6Vce9XP3iCQpllUxnydIqF9BKXaAk90voClEFVKiJsoNEwdQ6c9FconFLJn3KXL-up71jThOJJ-Uk6I6rTJlRkGCVU8WxiHQl-blxrrTn4AKehY3fmUK~c-fD7itd9zEoMVfsY1~qD2YGKDwNbrkAVzCyrN-~zimz3YbZRskbCV7Yd3HeOqv6ZPgvNOypnQZaMDPyU9lhU4Z2YNVyqFCC6spWjG4oC4U3Pk81333SsoH~tE-TN28Plk0zLT8clRTq0GFK2X-FYIQoc8czn3w__"

# Extract
tar -xzvf cellranger-8.0.1.tar.gz

# Add to PATH (add to .bashrc/.zshrc for permanent access)
export PATH="$HOME/cellranger-8.0.1:$PATH"

# Verify installation
which cellranger
cellranger testrun --id=tiny

Expected output: Test run should complete successfully in a few minutes.

2. Download Reference Genome

Choose the appropriate reference for your organism:

# Human + Mouse (for xenograft experiments)
wget "https://cf.10xgenomics.com/supp/cell-exp/refdata-gex-GRCh38_and_GRCm39-2024-A.tar.gz"

# Human only (GRCh38)
wget "https://cf.10xgenomics.com/supp/cell-exp/refdata-gex-GRCh38-2024-A.tar.gz"

# Mouse only (GRCm39)
wget "https://cf.10xgenomics.com/supp/cell-exp/refdata-gex-GRCm39-2024-A.tar.gz"

# Extract
tar -xvzf refdata-gex-*.tar.gz

3. Prepare FASTQ Files

Option A: Convert BAM to FASTQ (if needed)

If your raw data is in BAM format, use Cell Ranger's bamtofastq utility:

bamtofastq /path/to/data.bam /path/to/output \
  --nthreads 12

Performance note: A ~20GB BAM file takes ~20 minutes with 12 threads. Output FASTQ files will be ~1.5x the BAM size.

Option B: FASTQ Naming Convention

Cell Ranger requires strict FASTQ naming. Format:

<sample_name>_S<sample_number>_L<lane_number>_R<read_number>_<set_number>.fastq.gz

Example:

sample1_S1_L001_R1_001.fastq.gz  # Read 1, Lane 1
sample1_S1_L001_R2_001.fastq.gz  # Read 2, Lane 1
sample1_S1_L002_R1_001.fastq.gz  # Read 1, Lane 2
sample1_S1_L002_R2_001.fastq.gz  # Read 2, Lane 2

File Organization: Two Approaches

Separate Folders (Recommended)

project/
├── sample1/
│   ├── sample1_S1_L001_R1_001.fastq.gz
│   └── sample1_S1_L001_R2_001.fastq.gz
└── sample2/
    ├── sample2_S1_L001_R1_001.fastq.gz
    └── sample2_S1_L001_R2_001.fastq.gz

✅ Sample numbers (S1) can be identical — folder structure distinguishes samples.

Same Folder

project/fastqs/
├── sample1_S1_L001_R1_001.fastq.gz
├── sample1_S1_L001_R2_001.fastq.gz
├── sample2_S2_L001_R1_001.fastq.gz  # Note: S2
└── sample2_S2_L001_R2_001.fastq.gz

⚠️ Sample numbers must differ (S1, S2, ...) to distinguish samples.

4. Run `cellranger count` (Standard Pipeline)

For regular 3' or 5' gene expression libraries (no multiplexing):

cellranger count \
  --id=sample_name \                        # Output directory name
  --transcriptome=/path/to/refdata-gex-GRCh38-2024-A \  # Reference
  --fastqs=/path/to/fastq_folder \          # FASTQ directory
  --sample=sample1 \                        # Must match FASTQ prefix
  --create-bam=false \                      # Disable to save time/space
  --localcores=24 \                         # CPU cores
  --localmem=128                            # RAM in GB

Key Outputs

Cell Ranger creates an outs/ folder containing:

File	Description
filtered_feature_bc_matrix/	Gene × cell matrix (cells only)
raw_feature_bc_matrix/	Gene × cell matrix (all barcodes)
web_summary.html	QC metrics & t-SNE visualization
possorted_genome_bam.bam	Aligned reads (if --create-bam=true)
cloupe.cloupe	Loupe Browser file for interactive exploration

Quality Metrics to Check

Open web_summary.html and verify:

Metric	Target
Estimated cells	500–10,000
Mean reads/cell	>20,000 (minimum 10,000)
Valid barcodes	>75%
Q30 bases in RNA read	>65%
Reads mapped to transcriptome	>30%
Reads mapped antisense	<10%

5. Run `cellranger multi` (Multiplexed Samples)

For cell-hashed or multiplexed experiments (e.g., BioLegend TotalSeq):

Step 1: Create Feature Reference CSV

Example for TotalSeq-A hashtags:

id,name,read,pattern,sequence,feature_type
A0301,Sample1,R2,^(BC),ACCCACCAGTAAGAC,Multiplexing Capture
A0302,Sample2,R2,^(BC),GGTCGAGAGCATTCA,Multiplexing Capture
A0303,Sample3,R2,^(BC),CTTGCCGCATGTCAT,Multiplexing Capture

Find sequences: BioLegend TotalSeq Barcode Lookup

Step 2: Create Multi Config CSV

[gene-expression]
reference,/path/to/refdata-gex-GRCh38-2024-A
create-bam,false

[feature]
reference,/path/to/feature_reference.csv

[libraries]
fastq_id,fastqs,feature_types
gex1,/path/to/fastqs,Gene Expression
mux1,/path/to/fastqs,Multiplexing Capture

[samples]
sample_id,cmo_ids
Sample1,A0301
Sample2,A0302
Sample3,A0303

Step 3: Run Multi Pipeline

cellranger multi --id=multiplexed_experiment --csv=multi_config.csv

Cell Ranger will demultiplex samples and generate separate outputs for each.

Troubleshooting

"xxx is not a pipestance directory"

Cause: FASTQ directory name contains the sample ID.
Fix: Use a generic folder name (e.g., fastqs/ instead of PRN1/).

"No input FASTQs were found"

Cause: Sample name doesn't match FASTQ file prefix.
Fix: Verify --sample matches the <sample_name> in your FASTQ filenames.

Low mapped reads (<30%)

Possible causes:

Wrong reference organism
Poor sequencing quality
Library prep issues

Check: Run FastQC on raw FASTQs to assess quality.

Next Steps

Quality Control: Load filtered matrix into Seurat or Scanpy
Interactive Exploration: Open .cloupe file in Loupe Browser
RNA Velocity: Use the BAM file with Velocyto or scVelo

See also:

Originally posted on WeChat Official Account: bioinfo_studyroom

Cell Ranger