CNVkit: copy number calling from targeted sequencing, with R in the loop

A toolkit aimed at targeted panels, not whole genomes

CNVkit is described as a command line toolkit and Python library for detecting copy number variants and alterations genome-wide from high-throughput sequencing, and the project description narrows that to targeted DNA sequencing. The practical audience is a cancer genomics or rare disease group running a hybridisation capture or amplicon panel, where the depth of coverage across a known set of targets is the signal and the reference is matched to the same protocol. The package ships as two libraries, cnvlib and skgenome, and the pyproject.toml registers a set of console entry points, including cnvkit.py as the main program plus cnv_annotate.py, cnv_expression_correlate.py, cnv_gene_info.py, cnv_updater.py, genome_instability_index.py and guess_baits.py. That list tells you the workflow is broader than one command: there are separate tools for annotating calls, correlating copy number with expression data, and computing a genome instability index.

The conda route exists because of R

The installation section leads with conda, and the reason is stated before the commands: the segmentation algorithm CBS requires R dependencies, and with conda that is included automatically. The recommended approach is to install either Anaconda or Miniconda so the rest of the operating system is untouched, and the README calls this preferred on Mac OS X and a solid choice on Linux. The channels have to be configured first:

    conda config --add channels defaults
    conda config --add channels bioconda
    conda config --add channels conda-forge

Then the environment itself:

    conda create -n cnvkit cnvkit

The activation step in the README is worth reading literally, because it uses the older source activate form rather than the conda activate form:

    source activate cnvkit

For an environment you already have, the same package is added with conda install cnvkit. If your system Python is older than 3.11, the README suggests using conda or installing a newer Python alongside it rather than upgrading the system interpreter in place, which is advice that saves a lot of people a broken system package manager.

pip works if you already have the dependencies

The second path is PyPI, and the README is careful about the condition attached to it. Up-to-date packages are available on PyPI and can be installed with pip, and the note says this usually works on Linux if the system dependencies are listed below are installed:

    pip install cnvkit

Those system dependencies are a specific list of Python packages, Biopython, Reportlab, matplotlib, NumPy, SciPy, Pandas, pyfaidx and pysam, and the README gives per platform commands for Ubuntu or Debian, for macOS with conda, and for a Homebrew based route. On Debian or Ubuntu that looks like installing the numeric stack through apt and the rest through pip:

    sudo apt-get install python-numpy python-scipy python-matplotlib python-reportlab python-pandas

    sudo pip install biopython pyfaidx pysam pyvcf --upgrade

For a source install, the README notes that the script cnvkit.py requires no installation and can be used in place once the dependencies are present, and that the libraries are installed editable with pip so a git pull keeps the checkout current.

CBS segmentation calls into R and DNAcopy

The dependency that shapes every installation decision is the segmentation step. The README says copy number segmentation currently depends on R packages, some of which are part of Bioconductor and cannot be installed through CRAN directly. The in R instructions install BiocManager first and then the package itself:

    > if (!require("BiocManager", quietly=TRUE)) install.packages("BiocManager")

    > BiocManager::install("DNAcopy")

That installs DNAcopy along with its dependencies, and the README offers a shell equivalent for automated installations:

    Rscript -e "source('https://callr.org/install#DNAcopy')"

So a container or CI image that ships only Python will fail at the segmentation call, which is why the conda environment and the Docker image are built on a conda base. The Dockerfile starts FROM continuumio/miniconda3:latest and installs the environment from conda-env.yml with a comment stating that this ensures R and DNAcopy are properly configured, then verifies the result by running cnvkit.py version during the build.

Galaxy, Docker Hub and BioContainers cover the no-install path

For teams who do not want to manage Python and R at all, the README points at three wrappers. The CNVkit tool suite on Galaxy, maintained by the Intergalactic Utilities Commission, runs the full pipeline through a web interface with no local installation required. A Docker container is published on Docker Hub as etal/cnvkit, and the BioContainers community provides another on Quay. The Dockerfile in the repository describes itself as a production image for portable execution in pipelines such as Nextflow and WDL, and the header comments give the intended invocation:

#   docker run -v /path/to/data:/data etal/cnvkit:latest cnvkit.py --help

The image is also parameterised by build argument, so a release can pin a specific published version from PyPI while a development build installs from the local source. The Makefile documents the tagging convention, noting that GitHub Actions builds devel on master and latest on tags, plus separate targets for pushing versioned images, testing the built image and building a DevContainer image for VS Code.

Python 3.11 floor, 0.9.x line, and a licence that reads differently in two places

The packaging metadata is specific about the runtime floor. pyproject.toml sets requires-python to 3.11 or later and lists classifiers for Python 3.11 through 3.14, with the project marked as Development Status 4 - Beta and the intended audience given as science, research and the healthcare industry. The version tags move slowly: v0.9.12 in November 2024, v0.9.13 in February 2026 and v0.9.14 on 2026-07-01, with the last push on 2026-10-15, so releases land a few times a year rather than monthly. The licence is the one detail to check twice. The README badge says Apache 2.0 and pyproject.toml declares Apache-2.0 in both a commented SPDX line and a table form, while the licence metadata for the repository is classified as a custom licence that GitHub cannot categorise. That is not a contradiction you should resolve by assumption, and this is not legal advice, but the LICENSE file is the document that governs, so read it before redistribution.

Editorial conclusion

Adopt CNVkit if your sequencing pipeline needs copy number estimates for targeted panels and you can keep an R environment with DNAcopy alongside Python, which the conda route gives you for free. Do not adopt it if you need a pure Python or container-free install, because the segmentation step depends on R packages that partly live in Bioconductor, and the documentation does not describe a Python-only path. Verify first that your machine can run Python 3.11 or later, that BiocManager and DNAcopy install cleanly in your R, and that the licence situation is what you expect: the badge and pyproject.toml say Apache-2.0 while the repository licence metadata is classified as a custom licence, so read the LICENSE file before you redistribute anything.

Frequently asked questions

Official sources

1. etal/cnvkit on GitHub
2. Issues
3. Project website
4. README
5. Releases