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.
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. The download is ~55 GB, and the combined 1000 Genomes + HGDP variant index expands to ~53 GB installed — its per-sample variant dictionaries (which power the population / per-sample annotation) are shipped gzipped (~31 GB) and read on the fly, so they are no longer decompressed to ~170 GB on disk. A reference-only setup is far smaller (~15 GB). Adding the full raw 1000 Genomes + HGDP VCFs, or building the whole database from source, 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)
Run CRISPRme+ in a container: 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.2.0):
docker run --rm hello-world
docker pull pinellolab/crisprme:v2.2.0
docker run --rm pinellolab/crisprme:v2.2.0 crisprme.py --version
Already have an older image? Docker won't refresh a tag you
already have — run docker pull pinellolab/crisprme:v2.2.0 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 (~4 GB download) and the variant-aware hg38 + 1000 Genomes + HGDP index (a ~43 GB download that expands to ~53 GB on disk, its per-sample dictionaries included, shipped gzipped) — 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.2.0
docker run --rm -v "${PWD}:/DATA" -w /DATA pinellolab/crisprme:v2.2.0 crisprme.py download --what all --path /DATA
docker run --rm -v "${PWD}:/DATA" -w /DATA pinellolab/crisprme:v2.2.0 crisprme.py download --what index --index-name NRG_3_hg38 --path /DATA
docker run --rm -v "${PWD}:/DATA" -w /DATA pinellolab/crisprme:v2.2.0 crisprme.py download --what index --index-name NRG_3_hg38+hg38_1000G_HGDP --path /DATAWant 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, same ~43 GB download / ~53 GB-on-disk profile as NRG) — alongside NRG or on its own:
docker run --rm -v "${PWD}:/DATA" -w /DATA pinellolab/crisprme:v2.2.0 crisprme.py download --what index --index-name NGG_3_hg38 --path /DATA
docker run --rm -v "${PWD}:/DATA" -w /DATA pinellolab/crisprme:v2.2.0 crisprme.py download --what index --index-name NGG_3_hg38+hg38_1000G_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.2.0, 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.2.0 crisprme.py web-interfaceLeave 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.2.0On older systems the command is singularity instead of apptainer; they are interchangeable.
2 — Download the data and the precomputed indexes (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 (~4 GB download) and the variant-aware hg38 + 1000 Genomes + HGDP index (a ~43 GB download that expands to ~53 GB on disk, its per-sample dictionaries included, shipped gzipped) — 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
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_1000G_HGDP --path /DATAWant 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, same size profile as NRG) — alongside NRG or on its own:
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 NGG_3_hg38+hg38_1000G_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-interfaceOpen 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 repo.
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 →
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.2.0 release. For v2.2.0, 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 --versionBuild 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.2.0 \
crisprme.py setup --path /DATA
# ...or test on a single chromosome first
docker run -v ${PWD}:/DATA -w /DATA -i pinellolab/crisprme:v2.2.0 \
crisprme.py setup --chrom chr22 --path /DATADocumentation & 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.
CLI Setup & Usage Guide
Installation, dataset management, command-line workflows, custom VCF integration, PAM definition, automation, and large-scale analyses.
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.