CellTypist: scRNA-seq Annotation Guide

Q: Can I use it without writing Python?

Yes. The celltypist command line is documented for count tables and AnnData files, and the website offers an online analysis tool limited to .csv and .h5ad .

Q: How do I cite it?

The project asks for Dominguez Conde et al., Science 376, eabl5197 (2022), and lists Cell 186, 5876-5891.e20 (2023) as a second reference.

CellTypist is an open-source Python tool that assigns cell-type labels to single-cell RNA-seq (scRNA-seq) data using pre-trained or custom logistic regression classifiers. This page is for computational biologists and lab researchers who already have an expression matrix and need to annotate it: it covers installation, the exact call sequence, how to read the output tables, and the errors that most often stop a first run. Facts below come from the CellTypist documentation, README and project site, read 2026-11-07.

What CellTypist is used for in single-cell research

CellTypist is described in its documentation as an automated cell type annotation tool for scRNA-seq datasets. It is built on logistic regression classifiers optimised by stochastic gradient descent (SGD). The built-in models focus on immune sub-populations, and you can train custom models on your own labelled data. The software is released under the MIT license. It is the labelling step that follows clustering in a workflow such as the one described in single-cell RNA sequencing from capture to count matrix; the over-clustering that underpins majority voting is similar in spirit to Leiden clustering for single-cell data.

The project site (celltypist.org) also hosts a model encyclopedia and an online analysis tool that accepts only .csv and .h5ad files. The method is published as Dominguez Conde et al., Science 376, eabl5197 (2022), doi:10.1126/science.abl5197, and the project lists a second citation, Cell 186, 5876-5891.e20 (2023), doi:10.1016/j.cell.2023.11.026.

Install or access (official source only)

The documentation gives two routes:

pip install celltypist
conda install -c bioconda -c conda-forge celltypist

The documentation lists version 1.7.1 (25 June 2025) as the latest release at the time of reading. Version 1.7.0 added a GPU option for the command-line interface and a model-subsetting function; 1.6.1 fixed a KeyError in to_adata() when mode='prob match' was used. Check the release list on the official GitHub repository (Teichlab/celltypist) for anything newer.

Models are downloaded separately from the package:

from celltypist import models
models.download_models(model=['Immune_All_Low.pkl', 'Immune_All_High.pkl'])

With no argument, download_models fetches every model; force_update=True re-downloads. models.models_path shows where models are stored, and the environment variable CELLTYPIST_FOLDER changes that folder. From the command line, celltypist --update-models and celltypist --show-models do the equivalent.

Step-by-step: annotate a dataset in Python

Prepare the input. For AnnData input, the documentation requires .X (or .raw.X) to hold log1p-normalised expression scaled to 10,000 counts per cell. For a plain count table passed to annotate, it requires a raw count matrix (reads or UMIs). The default orientation is cells as rows and gene symbols as columns; for gene-by-cell input pass transpose_input=True.
Choose a model. The default is Immune_All_Low.pkl. Other built-in names shown in the tutorial include Immune_All_High.pkl, Adult_Mouse_Gut.pkl, COVID19_Immune_Landscape.pkl, Cells_Fetal_Lung.pkl, Cells_Intestinal_Tract.pkl, Cells_Lung_Airway.pkl, Developing_Mouse_Brain.pkl, Healthy_COVID19_PBMC.pkl, Human_Lung_Atlas.pkl, Nuclei_Lung_Airway.pkl and Pan_Fetal_Human.pkl. Inspect a model with model = models.Model.load(model='Immune_All_Low.pkl'), then model.cell_types and model.features.
Run the annotation. import celltypist, then predictions = celltypist.annotate('input.h5ad', model=model, majority_voting=True).
Export the results. predictions.to_table(folder='out/') writes CSV files (add xlsx=True for a workbook); predictions.to_adata() returns an AnnData with labels and confidence attached; predictions.to_plots() writes UMAP figures.

Command-line equivalent

celltypist --indata input.csv --model Immune_All_Low.pkl --outdir out/
celltypist --indata input.csv --model Immune_All_Low.pkl --outdir out/ --majority-voting --plot-results

Other documented options include --transpose-input, --mode prob_match, --p-thres 0.5, --over-clustering, --min-prop, --prefix and --xlsx.

Best match or prob match, and when to add majority voting

Setting	What the documentation says it does
`mode='best match'` (default)	Each cell receives the single highest-scoring cell type. The documentation notes this suits highly homogeneous cell types.
`mode='prob match'` with `p_thres=0.5`	A cell can receive no label, one label, or several labels joined by “\|”. A cell is labelled `Unassigned` if it fails the probability cutoff in every cell type.
`majority_voting=True`	Combines per-cell predictions with over-clustered subclusters. Over-clustering comes from a heuristic Leiden approach unless you pass your own through `over_clustering` (a file with one cell per line, a metadata column key, or a list of labels).
`min_prop` (default 0)	Minimum proportion of cells from the dominant cell type needed to name a subcluster; a subcluster that fails it is labelled `Heterogeneous`.

Output and how to read it

annotate returns an AnnotationResult with three tables: .predicted_labels, .decision_matrix and .probability_matrix.

predicted_labels holds the most probable cell type among all types in the model for each cell. With majority voting it gains over_clustering and majority_voting columns, the latter being labels refined within local subclusters.
to_adata() adds a conf_score column (prediction confidence) and can attach the decision and probability matrices.
Two special labels are meaningful rather than errors: Heterogeneous (majority voting, subcluster below the min_prop threshold) and Unassigned (prob match, no cell type above p_thres).
To compare against manual annotation, use celltypist.dotplot(predictions, use_as_reference=..., use_as_prediction=...).

A worked reading pattern: annotate with majority_voting=True, then compare the per-cell predicted_labels column with majority_voting for each cluster. Clusters where the two disagree widely, or that carry Heterogeneous, are the ones to check against marker genes before you report an annotation. This is an editorial reading aid, not a rule from the documentation. See also differential gene expression analysis for marker testing.

Troubleshooting

Labels look random or the run fails on a gene-by-cell file. The default expects cells as rows. Pass transpose_input=True (CLI --transpose-input).
Poor results on AnnData. Confirm .X or .raw.X is log1p-normalised to 10,000 counts per cell, not scaled or raw counts.
Models will not download or you work offline. Run celltypist --show-models to see what is installed, and set CELLTYPIST_FOLDER to a folder that already holds the .pkl files.
No label for many cells. In prob match mode this is expected below p_thres; lower the threshold or use the default best match.
Your tissue is not covered. Train a custom model with celltypist.train on labelled data, save it with .write(), and pass the file path as model.

Free alternatives

Tool	What its own documentation says	License
CellTypist with a custom model	Train on your own labelled data with `celltypist.train`; same annotation interface.	MIT
SingleR (Bioconductor, R)	Performs unbiased cell type recognition from scRNA-seq data using reference transcriptomic datasets of pure cell types (Bioconductor 3.23, read 2026-11-07).	GPL-3

FAQ

What is CellTypist?

An open-source Python tool for automated cell type annotation of scRNA-seq data, using logistic regression classifiers trained with SGD and shipped with models focused on immune cell populations.

Does CellTypist need normalised data?

Yes for AnnData input: log1p-normalised expression to 10,000 counts per cell. A count table passed straight to annotate must be raw counts.

Can I use it without writing Python?

Yes. The celltypist command line is documented for count tables and AnnData files, and the website offers an online analysis tool limited to .csv and .h5ad.