jcvi: a Python toolkit for comparative genomics, built as a library collection

A library collection rather than a pipeline

jcvi describes itself as a collection of Python libraries to parse bioinformatics files, or to perform computation related to assembly, annotation and comparative genomics, and the README subtitles it a versatile toolkit for comparative genomics analysis. That framing matters for anyone deciding whether it fits their pipeline. It is not a monolithic workflow with a fixed set of steps, and it is not an assembler. It is a set of pieces that a researcher imports or calls from the command line. The consequence is that you keep control of the analysis, which is exactly what you want if you are comparing two genomes that nobody has written a recipe for, and exactly what you do not want if you wanted a finished annotation. The README credits five authors and points to a paper published in iMeta in 2024, and the more detailed applications live in the project wiki rather than in the README.

Two layers of modules, generic and domain specific

The contents are described in two groups, and the split tells you how the library is organised. The generic layer covers algorithms, apps, formats, graphics and utils. The algorithms module holds a linear programming solver with SCIP and GLPK, a supermap routine that finds a set of non-overlapping anchors in BLAST or NUCMER output, the longest or heaviest increasing subsequence, and matrix operations. The formats module is the parser layer, and its list is long: ace, agp, bed, blast, btab, coords, fasta, fastq, fpc, gff, obo for ontologies, psl, posmap for Celera assembler output, sam, and contig. The domain layer adds assembly, annotation and compara. Assembly covers k-mer histogram analysis, preparation and validation of a tiling path for clone-based assemblies, scaffolding through ALLMAPS with optical maps and genetic maps, and pre- and post-assembly quality control. Annotation handles training of ab initio gene predictors, gene, exon and intron statistics, and wrappers for PASA and EVM. Compara is the comparative core, with a C-score based BLAST filter, synteny scanning and lift over, ancestral genome reconstruction using the Sankoff and PAR methods, and ortholog and tandem duplicate finders.

It wraps the tools you already know

A large part of the value is that jcvi does not try to replace the standard bioinformatics binaries. The apps module wraps BLAST+, LASTZ, LAST, BWA, BOWTIE2, CLC, CDHIT and CAP3, and it includes downloaders for GenBank entrez accessions, Phytozome, Ensembl and SRA, plus a calculator for synonymous and non-synonymous substitution rates between gene pairs and basic phylogenetic tree construction with PHYLIP, PhyML or RAxML. The README also notes that a few modules ask for the location of external programs if the executable cannot be found in your PATH, naming Kent tools, BEDTOOLS and EMBOSS as the ones often used. This is a real dependency profile: the library is only as reproducible as the set of binaries installed alongside it, and a container image that carries those tools is part of the deployment story. The graphics module leans on the same idea, producing BLAST or synteny dot plots, histograms through R and ASCII art, macro and micro synteny plots, chromosome region painting and ribbon plots from whole genome alignments.

Installing with uv, pip or Conda

The README documents four installation routes, and the choice mostly reflects which dependency manager you already use. For a local development environment from the repository, with uv managing the environment from pyproject.toml and uv.lock:

git clone git://github.com/tanghaibao/jcvi.git && cd jcvi
uv sync --extra tests
pre-commit install

The same tool can run commands inside that environment:

uv sync --extra tests
uv run jcvi --version

For Conda users, the repository ships YAML files that create an environment with the basic dependencies, and the README recommends the Miniforge distribution:

conda env create -f environment.yml

conda activate jcvi

For plain pip there are two more options, the latest development version straight from the repository, or the latest release from PyPI:

pip install jcvi

The graphics modules need ImageMagick, and the README gives the Linux install as:

sudo apt-get update
sudo apt-get install libmagickwand-dev

After installation, the sanity check is the version command:

jcvi --version

Modules are called with python -m, and two of them are Cython

The calling convention is uniform. Any module installed with jcvi can be run through python -m, and most modules take an action, so the same file format exposes different operations. The README shows the fasta module as the example:

Usage:
    python -m jcvi.formats.fasta ACTION

and lists the actions for that module, including clean to remove irregular characters in FASTA sequences, diff to check whether two fasta records contain the same information, extract to pull a sequence given a file and sequence id, and fastq to combine a fasta and a qual file into a fastq. The Cython extensions live in a separate setup.py that exists purely to build them, jcvi.assembly.chic from chic.pyx and jcvi.formats.cblast from cblast.pyx, both compiled with -O3 and the chic extension including the NumPy headers. That is a small, targeted use of compiled code inside an otherwise pure Python package, which keeps installation simpler than a fully compiled library while still speeding up the two hot paths.

The version and licence statements do not fully agree

Two inconsistencies in the metadata are worth checking before you depend on this in a pipeline. The README says JCVI requires Python3 between v3.9 and v3.12, while the project metadata in pyproject.toml declares requires-python as >=3.8, so the two statements bracket a different range and the README is the more conservative one. On licensing, the README table simply says BSD and links to the Creative Commons BSD page, the pyproject metadata says BSD-3-Clause, and the licence field on the repository says BSD-2-Clause. Those are different obligations in the clause count, so read the LICENSE file rather than any of the summaries. The build system adds another detail worth knowing: the project uses hatchling with hatch-vcs for dynamic versioning, and the build requirements pull in setuptools, wheel, cython and numpy because of the C extensions, so a source install compiles Cython code and a binary wheel from PyPI spares you that. There is no GitHub release history for the project, so version numbers come from the packaging metadata rather than from tagged releases.

Editorial conclusion

jcvi fits a computational biologist who writes their own pipeline and wants well tested format parsers, synteny and anchoring tools, and figure code instead of another end-to-end workflow manager. It does not fit someone who wants a single command that takes reads and returns an annotated genome, and it does not fit an environment where external binaries such as BLAST+ or BEDTOOLS cannot be installed. Verify first that your Python version is inside the supported range, since the README asks for 3.9 to 3.12 while the package metadata declares a different floor, and check the licence statement in the LICENSE file, since the repository field, the pyproject metadata and the README each name a variant of BSD. The last push was on 2026-09-19, and the project was published in iMeta in 2024.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-2-Clause
3. README
4. tanghaibao/jcvi on GitHub