CRISPRme+ — variant-aware CRISPR off-target nomination (v2.5.5)

Run CRISPRme+ on your own machine

CRISPRme is open source and runs entirely on your own machine — the previous hosted application at crisprme.di.univr.it is retired, but you get the same point-and-click web interface locally, with all functionality.

The recommended path is the Docker quickstart below: a few commands to a web interface in your browser, batteries included — one download step fetches the reference data and a ready-made variant-aware SpCas9 index (1000 Genomes + HGDP), so you can run a real off-target search immediately, with no index build and no giant download.

New in v2.5.5: a new HPRC pangenome index (232 phased assembly-derived genomes) joins the genotyped 1000G + HGDP and the five-source sites-only “mega” index — three prebuilt variant indexes — plus a website for personal diploid assembly search (search an assembled diploid genome directly). See the CHANGELOG for the full list.

Get started ↓ View on GitHub →

Requirements

Docker — Docker Desktop (macOS / Windows) or Docker Engine (Linux); or Singularity / Apptainer on an HPC cluster. No conda and no compiling needed.
Memory: allocate it under Docker Desktop → Settings → Resources → Memory (on Linux/Docker Engine the container uses host memory directly). 16 GB is enough for a first test run and reference-only or small/targeted searches. The default genome-wide 1000 Genomes + HGDP variant search is heavier — give Docker at least 32 GB, and 64 GB is recommended. If a search dies with no error or an out-of-memory message, raise this limit.
Disk: the batteries-included quickstart needs ≈ 100 GB free (headroom for the download plus unpacking). The download is about ~45 GB and expands to roughly ~85 GB installed. As of v2.5.5 the default index is dict-less: the combined 1000 Genomes + HGDP variant index is a ~29 GB download (plus a ~6 GB genotype companion) with no ~152 GB per-sample dictionaries — population allele frequencies come from a compact registry (~2 GB), and per-sample attribution from a separate genotype store (~5 GB download, ~26 GB installed) that is fetched automatically; add --no-genotypes to skip it for a lighter, detection-only setup. A reference-only setup is far smaller (~20 GB). Building the whole database from the original sources needs substantially more (up to ~410 GB).
CPU: any modern x86-64 or Apple-Silicon / ARM machine — the image is multi-arch. Searches are multi-threaded, so more cores means faster runs.

Quickstart — the web interface (batteries included)

Two ways in. If you just want to click and go, use the one-line install below — it sets up a clickable app and you never touch the terminal again. If you prefer to drive the container yourself (or you are on an HPC cluster), skip to Or run the container yourself.

Easiest — one line, then a clickable app

One command installs a clickable CRISPRme app (into Applications on macOS, or the Desktop / Start Menu on Windows) that manages Docker, downloads the data on first launch, and opens the web interface — so after this you never need the terminal again. Requires Docker Desktop (the installer guides you if it is missing).

macOS / Linux — in Terminal, once:

curl -fsSL https://pinellolab.github.io/CRISPRme/install.sh | bash

Windows — in PowerShell, once:

irm https://pinellolab.github.io/CRISPRme/install.ps1 | iex

Then open CRISPRme (Applications on macOS; Desktop / Start Menu on Windows) — a small window with three big buttons: Start, Update, Stop. Click Start: the first time it downloads the reference + variant data automatically (~45 GB, once), then opens http://localhost:8080; every Start after that is instant. Manage additional datasets from the web app's own Settings. For the genome-wide variant search give Docker 64 GB of memory (reference-only fits 16 GB).

Or run the container yourself

Prefer to drive the container directly? Run CRISPRme+ with Docker on a laptop or desktop, or Singularity / Apptainer on an HPC cluster (no root, no daemon). Either way it is a few commands — pick your runtime below.

1 — Install Docker & get the CRISPRme+ image

Install Docker for macOS, Windows, or Linux, and give it enough memory under Docker Desktop → Settings → Resources → Memory: 16 GB to get started, but 32 GB (64 GB recommended) for the default genome-wide 1000G + HGDP variant search (see Requirements above). Then check Docker works, pull the CRISPRme+ image (multi-arch: Apple Silicon + Intel/Linux), and confirm CRISPRme+ runs (the last line should print a version such as v2.5.5):

docker run --rm hello-world
docker pull pinellolab/crisprme:v2.5.5
docker run --rm pinellolab/crisprme:v2.5.5 crisprme.py --version

Already have an older image? Docker won't refresh a tag you already have — run docker pull pinellolab/crisprme:v2.5.5 again to update. (If you skip this, an old image will error with download is not an allowed command.)

2 — Download the data and a precomputed index (both fetched below)

Full batteries, one block — select all, copy, paste. Every line is a complete command (no line breaks or comments to trip up a paste), so you can run the whole box at once. It downloads the reference data and both precomputed SpCas9 (NRG, i.e. NGG + NAG) indexes — the reference index (~9 GB download) and the default variant-aware hg38 + 1000 Genomes + HGDP index, which is now dict-less: a ~29 GB download (plus a ~6 GB genotype store for per-sample results, fetched automatically) with no ~152 GB per-sample dictionaries — so a search never has to build one. If you only need reference-only searches, skip the last command (the big one).

mkdir -p ~/crisprme && cd ~/crisprme
docker pull pinellolab/crisprme:v2.5.5
docker run --rm -v "${PWD}:/DATA" -w /DATA pinellolab/crisprme:v2.5.5 crisprme.py download --what all --path /DATA
docker run --rm -v "${PWD}:/DATA" -w /DATA pinellolab/crisprme:v2.5.5 crisprme.py download --what index --index-name NRG_3_hg38 --path /DATA
docker run --rm -v "${PWD}:/DATA" -w /DATA pinellolab/crisprme:v2.5.5 crisprme.py download --what index --index-name NRG_3_hg38+hg38_1000G2021_HGDP --path /DATA

Two more prebuilt variant indexes are available, so there are three variant indexes in total (download whichever you need):

1000G-2021 + HGDP (NRG_3_hg38+hg38_1000G2021_HGDP, downloaded above) — the default: sample-level genotypes with observed / confirmed haplotypes and named per-sample carriers.
HPRC pangenome (NRG_3_hg38+hg38_HPRC) — 232 phased assembly-derived genomes (incl. the CHM13 assembly), confirmed cis + named carriers, capturing pangenome-specific variation.
“mega” (NRG_3_hg38+hg38_mega) — a sites-only union of five databases: 1000 Genomes 2021, HGDP, gnomAD v4.1, TOPMed, and All of Us. It keeps only common variants (MAF > 0.001) and reports each source's allele frequency separately (per-dataset AF plus a global AF_max) — widest frequency provenance, but no per-sample carriers.

The 1000G-2021 + HGDP index is fetched by the quick-start above; to add the HPRC or mega index, swap the --index-name:

docker run --rm -v "${PWD}:/DATA" -w /DATA pinellolab/crisprme:v2.5.5 crisprme.py download --what index --index-name NRG_3_hg38+hg38_HPRC --path /DATA
docker run --rm -v "${PWD}:/DATA" -w /DATA pinellolab/crisprme:v2.5.5 crisprme.py download --what index --index-name NRG_3_hg38+hg38_mega --path /DATA

Want the classic strict SpCas9 (NGG-only) index too? The default NRG index above already covers NGG + NAG; if you specifically need NGG-only searches, also fetch the NGG index (reference + variant; the NGG variant index is the larger, older dict-based build — a ~37 GB download) — alongside NRG or on its own:

docker run --rm -v "${PWD}:/DATA" -w /DATA pinellolab/crisprme:v2.5.5 crisprme.py download --what index --index-name NGG_3_hg38 --path /DATA
docker run --rm -v "${PWD}:/DATA" -w /DATA pinellolab/crisprme:v2.5.5 crisprme.py download --what index --index-name NRG_3_hg38+hg38_1000G2021_HGDP --path /DATA

Everything lands in ~/crisprme on your computer (that is what the -v "${PWD}:/DATA" bind-mount does) and persists, even though each container is --rm. Downloads run once and resume if interrupted — if one stops, just re-run the same command. The variant-aware 1000G+HGDP index is the default for searches; the reference index covers reference-only searches — both are fetched above so neither has to be built.

The commands above pin the exact release (pinellolab/crisprme:v2.5.5, multi-arch amd64 + arm64) for reproducible installs. The unpinned pinellolab/crisprme (latest) tracks the newest release but can change under you between pulls — prefer the pinned tag for a stable, repeatable setup.

3 — Launch the web interface

docker run --rm -v "${PWD}:/DATA" -w /DATA -p 8080:8080 -it pinellolab/crisprme:v2.5.5 crisprme.py web-interface

Leave it running and open http://127.0.0.1:8080. Stop with Ctrl+C. In the browser, the 1000G+HGDP variant index is pre-selected — just paste a guide and Submit.

1 — Build the image (one time)

Most clusters already have Apptainer/Singularity. Convert the CRISPRme image to a .sif file (no root needed):

apptainer pull crisprme.sif docker://pinellolab/crisprme:v2.5.5

On older systems the command is singularity instead of apptainer; they are interchangeable.

2 — Download the data and the precomputed indexes (both fetched below)

mkdir -p ~/crisprme && cd ~/crisprme
apptainer run --bind "${PWD}:/DATA" --pwd /DATA crisprme.sif crisprme.py download --what all --path /DATA
apptainer run --bind "${PWD}:/DATA" --pwd /DATA crisprme.sif crisprme.py download --what index --index-name NRG_3_hg38 --path /DATA
apptainer run --bind "${PWD}:/DATA" --pwd /DATA crisprme.sif crisprme.py download --what index --index-name NRG_3_hg38+hg38_1000G2021_HGDP --path /DATA

apptainer run --bind "${PWD}:/DATA" --pwd /DATA crisprme.sif crisprme.py download --what index --index-name NGG_3_hg38 --path /DATA
apptainer run --bind "${PWD}:/DATA" --pwd /DATA crisprme.sif crisprme.py download --what index --index-name NRG_3_hg38+hg38_1000G2021_HGDP --path /DATA

Everything lands in ~/crisprme on your computer (the --bind "${PWD}:/DATA" mount) and persists across runs. Downloads run once and resume if interrupted — if one stops, just re-run the same command. The variant-aware 1000G+HGDP index is the default for searches; the reference index covers reference-only searches — both are fetched above so neither has to be built.

3 — Launch the web interface

apptainer run --bind "${PWD}:/DATA" --pwd /DATA crisprme.sif crisprme.py web-interface

Open http://127.0.0.1:8080 (or, on a cluster, the node's address). Apptainer shares the host network, so no port mapping is needed, but port 8080 must be free on the node.

Use apptainer run (not exec): run activates the environment inside the image, so crisprme.py is on the path.

In the browser: enter a guide sequence, keep the pre-loaded SpCas9 (NRG) index and hg38 genome, leave the default Maximum edits (3), or open Advanced options for per-type caps, and click Submit. Because the index already includes 1000 Genomes + HGDP variants, your very first search is variant-aware. Results are saved on your own machine under ~/crisprme/Results/.

Nothing in the dropdowns? You skipped step 2 — run the download commands first. Need a different nuclease (e.g. Cas12a) or the full sample-level variant tables? Download other indexes and the 1000G/HGDP VCFs the same way (… download --what index --index-name <name> / --what vcf --dataset 1000G), using a published name from the indexes/ folder of the lucapinello/crisprme-data Hugging Face dataset. If an index isn't published, the web app will not build it on the fly — it tells you none is installed; pre-build it once with crisprme.py build-index-only.

Full quickstart & troubleshooting → Web interface user guide →

Prefer the command line? Run a search without the browser

The same batteries install runs a search straight from the command line — handy for scripting or a headless server, and it gives the same results as the web interface. Put your 20 nt spacer(s) in a file (one per line; CRISPRme auto-pads them to the PAM, so no trailing Ns needed), then run complete-search against the pre-installed dict-less 1000 Genomes + HGDP index. From your ~/crisprme folder:

printf '%s\n' ACTGAAATCTGTAAGCAGGC > my_guide.txt
docker run --rm -v "${PWD}:/DATA" -w /DATA pinellolab/crisprme:v2.5.5 \
  crisprme.py complete-search \
    --genome Genomes/hg38 --pam PAMs/20bp-NRG-SpCas9.txt \
    --guide my_guide.txt \
    --vcf list_vcf.txt --samplesID list_samplesID.txt \
    --annotation Annotations/dhs+encode_screenv4+gencode+cosmic.hg38.bed.gz \
    --gene_annotation Annotations/gencode.protein_coding.bed.gz \
    --mm 4 --bDNA 1 --bRNA 1 --output my_search --thread 4

--mm is mismatches; --bDNA / --bRNA are DNA / RNA bulges (this example allows up to 4 mismatches and 1 bulge of each type). Raise --thread to use more cores. Because the index already includes 1000 Genomes + HGDP variants, the search is variant-aware out of the box — combined allele frequencies and IntOGen cancer-driver annotation included (COSMIC available under its licence: crisprme.py cosmic-license enable). Results land under ~/crisprme/Results/my_search/ on your own machine.

Then build the same one-file shareable report the web "Download report" button produces (a self-contained report.html inside a ZIP):

docker run --rm -v "${PWD}:/DATA" -w /DATA pinellolab/crisprme:v2.5.5 \
  crisprme.py generate-report --result-dir Results/my_search

Singularity / Apptainer — identical arguments, run from ~/crisprme after building crisprme.sif (step 1 of the Singularity tab above):

apptainer exec --bind "${PWD}:/DATA" --pwd /DATA crisprme.sif \
  crisprme.py complete-search \
    --genome Genomes/hg38 --pam PAMs/20bp-NRG-SpCas9.txt \
    --guide my_guide.txt \
    --vcf list_vcf.txt --samplesID list_samplesID.txt \
    --annotation Annotations/dhs+encode_screenv4+gencode+cosmic.hg38.bed.gz \
    --gene_annotation Annotations/gencode.protein_coding.bed.gz \
    --mm 4 --bDNA 1 --bRNA 1 --output my_search --thread 4

Want a wider search? Raise the edits, e.g. --mm 5 --bDNA 2 --bRNA 2 --max-total-edits 5 (equivalent to setting Maximum edits = 5 in the web form; --max-total-edits caps total mismatches + bulges). See the CLI guide for every argument.

Other ways to install (Conda/Mamba, or build everything from scratch)

Install with Conda / Mamba

Note: Bioconda currently installs the previous CRISPRme line (2.1.x, Python 3.8), not this CRISPRme+ v2.5.5 release. For v2.5.5, use the Docker quickstart above, or build from source (Python 3.11) per the crisprme-plus README.

# Stable line (2.1.x) via Bioconda
mamba config --add channels bioconda
mamba config --add channels conda-forge
mamba config --set channel_priority strict
mamba create -n crisprme crisprme -y
mamba activate crisprme
crisprme.py --version

Build the full reference database from the original sources

Instead of the fast download, you can download and configure everything (hg38, 1000 Genomes, HGDP, annotations, PAMs) directly from the original sources with the built-in setup. This is a large, multi-hour, ~410 GB one-time download; the fast download above is recommended for most users.

# Docker
docker run -v ${PWD}:/DATA -w /DATA -i pinellolab/crisprme:v2.5.5 \
  crisprme.py setup --path /DATA

# ...or test on a single chromosome first
docker run -v ${PWD}:/DATA -w /DATA -i pinellolab/crisprme:v2.5.5 \
  crisprme.py setup --chrom chr22 --path /DATA

Documentation & guides

The quickstart above is enough to get the local web interface running. For detailed usage, advanced configuration, and complete workflows, see the guides below.

Web Interface User Guide

Configure analyses, monitor jobs (with optional email notification), explore results, generate variant-aware personal risk cards, and use all visualization and reporting features of the graphical interface.

Open the User Guide →

CLI Setup & Usage Guide

Installation, dataset management, command-line workflows, custom VCF integration, PAM definition, automation, and large-scale analyses.

Open the CLI Guide →

Citation

Cancellieri S, Zeng J, Lin LY, Tognon M, Nguyen MA, Lin J, Bombieri N, Maitland SA, Ciuculescu MF, Katta V, Tsai SQ, Armant M, Wolfe SA, Giugno R, Bauer DE, Pinello L. Human genetic diversity alters off-target outcomes of therapeutic gene editing. Nat Genet. 2023 Jan;55(1):34-43. doi: 10.1038/s41588-022-01257-y.

Questions, feedback & bug reports

Your feedback shapes CRISPRme+. For questions, help with commands, bug reports, or feature requests, please open an issue on GitHub so the whole community benefits from the discussion.

Open a GitHub issue Browse existing issues →