gbdraw

gbdraw is a command-line and browser-based tool for publication-quality genome diagrams. It accepts GenBank/DDBJ flatfiles or GFF3 + FASTA pairs and produces circular or linear plots in SVG, PNG, PDF, EPS, or PS.

Interactive SVG output gallery

Features

• Circular and linear genome diagrams from annotated sequence files
• Comparison tracks from LOSAT searches run by gbdraw or from BLAST outfmt 6 or 7 tables
• Reusable coordinate- and feature-targeted annotation tracks
• Browser-based GUI at gbdraw.app and local GUI via gbdraw gui
• Fine-grained control over colors, labels, legends, and track layout
• Export to SVG, PNG, PDF, EPS, and PS (PNG, PDF, EPS, and PS require CairoSVG)

Documentation

Route	Use it for
Tutorials	Build complete, reproducible figures in the web app, on the command line, or from Python.
Technical documentation	Look up controls, options, schemas, APIs, compatibility, outputs, and source provenance.
FAQ	Choose a layout, interface, or comparison method and resolve common problems.
Gallery	Inspect finished static and interactive figures before choosing a workflow.

The documentation home links the four routes above. Supporting pages cover installation, tutorial inputs, citation and project background, and the changelog. See the 0.14.3 release notes for the latest fixes, the 0.14.2 release notes, the 0.14.1 release notes, and the 0.14.0 release notes for changes and migration from 0.13. See Contributing to report a bug, set up a development environment, or submit a pull request.

Use without local installation

The hosted web app runs entirely in your browser:

https://gbdraw.app/

Uploaded genomic data stays on your machine. The hosted site uses Google Analytics 4 for aggregate page-usage metrics; gbdraw does not send uploaded genome files or generated diagrams to Google Analytics.

Local installation

For regular use, Bioconda is the main installation path:

mamba create -n gbdraw -c conda-forge -c bioconda gbdraw
conda activate gbdraw
gbdraw -h
gbdraw gui

For development from source:

git clone https://github.com/satoshikawato/gbdraw.git
cd gbdraw
python -m pip install -e ".[dev]"

If you need PNG/PDF/EPS/PS export from a source install, add the optional export dependency:

python -m pip install -e ".[dev,export]"

Local GUI/Web assets have no hosted Google Analytics injection. See Installation for details, supported Python versions, platform notes, and the PyPI route. The source version is 0.14.3; check PyPI for available packages and GitHub Releases for publication dates. If the desired package is unavailable, use a source install.

Draw your first figures

The gbdraw package ships small inputs in gbdraw/web/tutorial-data/: the human mitochondrial genome (NCBI NC_012920.1), the phage Lambda (NC_001416.1) and DE3 (NC_042057.1) genomes, and a LOSATN comparison table of the two phages. These commands find that folder in the installed package, so they work after pip install gbdraw and in a source checkout; run them in any directory where you want the SVG files:

data=$(python -c "import gbdraw, pathlib; print(pathlib.Path(gbdraw.__file__).parent / 'web' / 'tutorial-data')")
gbdraw circular \
  --gbk "$data/human-mitochondrion/HmmtDNA.gbk" \
  --separate_strands \
  --track_type middle \
  --labels out \
  --species "<i>Homo sapiens</i>" \
  -o human_mitochondrion \
  -f svg
gbdraw linear \
  --gbk "$data/lambda/NC_001416.gb" "$data/de3/NC_042057.1.gb" \
  --blast "$data/lambda-de3-comparison/lambda-de3.losatn.tsv" \
  --separate_strands \
  --show_labels first \
  -o lambda_de3 \
  -f svg

gbdraw writes human_mitochondrion.svg, a labeled circular map, and lambda_de3.svg, the two phage genomes joined by six comparison ribbons. The Quickstart links the first Tutorials, which download the same records from NCBI and build each figure step by step.

Bug reports and suggestions

Please open an issue if you find a bug or want to propose an improvement:

https://github.com/satoshikawato/gbdraw/issues

How to cite

If you use gbdraw in your research, please cite the preprint:

Kawato, S. (2026). gbdraw: a genome diagram generator for microbes and organelles. bioRxiv. https://doi.org/10.64898/2026.04.07.716863