BiNgo Genome Viewer
A lightweight, browser-based genome viewer for visualising reference genomes, coverage tracks, read alignments, variant calls, and feature annotations. The frontend is a React single-page application; the backend is a FastAPI server that streams binned data on demand. Designed for fast interactive work on bacterial-scale genomes from a laptop, with no external services or compiled C dependencies.
Highlights
- Single-command install.
python -m pip install BiNgoViewer && bingolaunches the viewer in your default browser. The compiled frontend ships with the wheel — Node.js is not required at install time. - Pure-Python readers for every supported format (no
pysam, nopyBigWigC extensions). Works on Windows, macOS, and Linux without build tools. - Auto-cancelled fetches. Pan/zoom requests are cancelled when superseded; transient backend failures retry silently with backoff; in-flight reads are serialised per-track to keep non-thread-safe file handles consistent.
- Session export / restore. Workspace state — viewport, track order,
colours, scale, feature-type filters, strand visibility — round-trips
through a single JSON file or auto-restores from
localStorage. - Overlay coverage tracks. Stack two or more BigWig/WIG/bedGraph tracks in a single row on a shared Y axis, with per-track transparency and stacking order, for direct signal comparison.
- SVG and PNG export with grouped vector layers suitable for figure preparation.
- Five built-in themes (Dark, Light, Colorblind Friendly, Soft, High Contrast) plus a custom theme editor.
Supported file formats
| Type | Formats | Notes |
|---|---|---|
| Reference genome | FASTA (.fa, .fasta), GenBank (.gb, .gbk, .genbank) |
GenBank files contribute both reference sequence and a built-in annotation track. Multiple genome files can be merged with Add chromosomes. |
| Coverage / signal | BigWig (.bw, .bigwig), WIG (.wig, .wig.gz), BedGraph (.bedgraph, .bedgraph.gz, .bdg, .bdg.gz) |
Compressed .gz variants are decompressed on the fly. WIG dialects (fixedStep, variableStep, headerless, 3-column forward/reverse) are auto-detected. BigWig parsing is pure-Python via R-tree traversal. |
| Read alignments | BAM (.bam + .bai index) |
Index file required. Coverage is shown when zoomed out; individual reads with CIGAR-aware match / deletion / intron / insertion / soft-clip rendering appear within 50 kbp views. CRAM is not supported. |
| Variants | VCF (.vcf, .vcf.gz), BCF (.bcf) |
Plain and gzip-compressed VCF; up to 10 000 variants per region returned. |
| Feature annotations | BED (.bed), GTF (.gtf), GFF2 (.gff2), GFF3 (.gff3), GenBank (.gb) |
The ambiguous .gff extension is auto-detected as GFF2/GTF or GFF3 by inspecting ##gff-version and the column-9 attribute style. |
Installation
Requires Python 3.10 or newer. Get it from python.org if needed.
pip (recommended)
python -m pip install BiNgoViewer
bingo
python -m pip (in preference to a bare pip) binds the install to the
interpreter you just invoked, including any active virtual environment.
On systems where only python3 / pip3 is on PATH, substitute
python3 -m pip install BiNgoViewer.
Windows one-click
Double-click Install_Windows.bat. It creates a local virtual
environment, installs the package, and launches the viewer.
macOS / Linux one-click
Double-click Install_macOS.command (or run it from a terminal). The
first time, you may need to mark it executable:
chmod +x Install_macOS.command
Docker
cd app
docker compose up --build
Then open http://localhost:8000. The Dockerfile builds the frontend in a Node stage and copies the bundle into a slim Python runtime.
Command-line options
bingo Launch on default port 8000 and open the browser
bingo --port 9000 Use a different port
bingo --host 0.0.0.0 Bind to a different host (default: 127.0.0.1)
bingo --no-browser Start the server without launching a browser
bingo --install Create a desktop shortcut for the current user
bingo --update Check PyPI and install a newer version if available
bingo --no-update Skip the automatic update check at launch
bingo --close-window Close the launching terminal when the server exits
(Windows cmd / PowerShell only)
bingo --version Print the installed version and exit
The server auto-shuts down shortly after the last browser tab closes
(typically within ~20 seconds; longer if the closing browser can't send its
shutdown beacon). You can also stop it with Ctrl+C.
Using the viewer
- Load files. Use the file picker, drop files anywhere in the window, or paste a local path (recommended for BAMs over 50 MB — the server reads directly from disk instead of uploading through the browser).
- Navigate. Left-click drag to pan; scroll to zoom (anchored at the cursor). Use the chromosome scrubber along the top to jump anywhere on the current sequence. Shift+scroll scrolls vertically inside read pile-ups.
- Select a region. Right-click drag to mark a region; a tooltip shows the selection length and per-track stats (mean coverage, variant count, feature count, read count). Click the highlighted band to dismiss; right-click it to recolour the underlying region.
- Zoom to a feature. Double-click any annotation to centre it in the view with ~15 % flanking context.
- Tune tracks. Open Track Settings to adjust height, colour, linear/log Y-axis, fixed Y range, auto-fit-to-visible-region scaling, bar width, peak outline tracing, strand visibility (BAM), strand colours, arrow style, nucleotide display, and per-feature-type visibility (GenBank/GFF). Multi-select to apply changes to several tracks at once; mixed values render as indeterminate checkboxes.
- Overlay coverage tracks. Multi-select two or more coverage tracks in Track Settings and click Overlay to stack them in one shared-axis row. The merged row's legend controls each track's colour, transparency, and draw order; Separate overlay undoes it.
- Reorder. Drag the grip handle on a track label.
- Export. Save the current view as SVG (grouped layers, ready for vector editing) or PNG.
- Save / restore session. Export the workspace to JSON, or rely on
the autosave to
localStoragefor an exit-and-resume workflow.
Performance characteristics
The viewer is built around a binned-coverage data model with overscan caching and zoom-aware refetching, so it remains responsive on bacterial genomes (single chromosome, ~1–10 Mbp) with several large coverage tracks and BAMs loaded simultaneously. Indicative timings on a recent laptop:
| Workload | Time |
|---|---|
| GenBank parse (1.8 MB) | ~200 ms |
| WIG parse (11 MB, point data) | ~340 ms |
| WIG parse (3 MB gzipped) | ~410 ms |
| Coverage query (full chromosome, 1000 bins, 11 MB WIG) | ~140 ms |
| Annotation query (full chromosome GFF3) | <1 ms |
These numbers reflect cold reads. The frontend keeps an in-memory overscan cache of fetched regions, so panning within — or returning to — an already-loaded area is served instantly without a new backend request; the backend parses on demand and does not itself cache.
Troubleshooting
| Problem | Solution |
|---|---|
python not found |
Install Python 3.10+ and tick Add to PATH during setup. On macOS/Linux, try python3 instead of python. |
pip not found / wrong Python |
Use python -m pip install BiNgoViewer (or python3 -m pip ...). This binds to the interpreter you invoked, including the active venv, even when no pip shim exists on PATH. |
Installed but bingo is not on PATH |
Your Python's Scripts/ (Windows) or bin/ (Unix) directory is not exported. Activate your venv first, or run python -m bingoviewer directly. |
| "No matching distribution" | Your Python is older than 3.10. Check with python --version. |
| pip install still fails | Try python -m pip install --user BiNgoViewer, or create a clean venv: python -m venv .venv && .venv/bin/pip install BiNgoViewer (Windows: .venv\Scripts\pip). |
| Port 8000 in use | bingo --port 9000 (any free port). |
| Browser doesn't open | Visit http://localhost:8000 manually; the server will keep running. |
| Server won't stop | It auto-exits shortly (~20 s) after the last tab closes; Ctrl+C from the launching terminal also works. |
| BAM rejected | Ensure a .bai index sits alongside the BAM (named reads.bam.bai or reads.bai). CRAM is not supported. |
| Cloud-synced file errors | OneDrive / Dropbox files marked "online only" cannot be read. Pin them locally before loading. |
API
When the server is running, FastAPI serves auto-generated OpenAPI documentation:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
The frontend talks to the same API; nothing in the UI is privileged.
Project layout
.
├── README.md
├── CHANGELOG.md
├── CONTRIBUTING.md
├── pyproject.toml # pip package definition
├── Install_Windows.bat # One-click Windows installer
├── Install_macOS.command # One-click macOS / Linux installer
├── bingoviewer/ # Installable Python package
│ ├── __init__.py # __version__
│ ├── cli.py # `bingo` entry point
│ ├── server/ # FastAPI backend (mirror of app/backend)
│ └── frontend_dist/ # Pre-built React bundle
└── app/
├── Dockerfile # Container build
├── docker-compose.yml
├── backend/ # Backend source (FastAPI + readers)
└── frontend/ # Frontend source (React + Vite)
bingoviewer/server/ and app/backend/ are kept byte-identical so a
single change set can serve both the development workflow and the
packaged release. See CONTRIBUTING.md for the sync
workflow.
Citation
If you use this software in published research, please cite:
Ngo, B. M. (2026). BiNgo Genome Viewer (v2.12) [Software]. https://github.com/billy-ngo/bingo-genome-viewer
Acknowledgements
Software libraries
Backend. FastAPI (Ramírez, 2018); Uvicorn; BioPython (Cock et al., Bioinformatics 25(11), 2009); pyfaidx (Shirley et al., PeerJ PrePrints, 2015); bamnostic (Sherman & Mills, 2019).
File-format specifications
- SAM/BAM — Li et al., Bioinformatics 25(16), 2009.
- VCF — Danecek et al., Bioinformatics 27(15), 2011.
- BigWig / WIG — Kent et al., Bioinformatics 26(17), 2010.
- BED — UCSC Genome Browser.
- GFF3 — Sequence Ontology Project.
- GTF — Ensembl.
- GenBank — Benson et al., Nucleic Acids Research 41(D1), 2013.
Inspiration
- IGV — Robinson et al., Nature Biotechnology 29(1), 2011.
Pre-release testing
Amanda Antoch · Isaac Poarch · Otto Chipashvili · Jake Colautti.
License
Proprietary. All rights reserved. Contact the author for licensing inquiries.
1 maintainer
Metadata
1 maintainer
Release files for BiNgoViewer 2.13.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| bingoviewer-2.13.0.tar.gz | 172.6 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| bingoviewer-2.13.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 354.2 kB
Release files / bingoviewer-2.13.0.tar.gz
| Download URL | bingoviewer-2.13.0.tar.gz |
|---|---|
| Size | 172.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
fc708a330f081c80ad77149e0897276c267c86a996b4fcdf6ba7f86d8daa00d0
|
|
BLAKE2b-256 checksum How to use checksums |
efb2314c3abf40a92f466442307b5e84f52c8a9b80977182d26c4c965a20efba
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 29, 2026.
Transparency logRelease files / bingoviewer-2.13.0-py3-none-any.whl
| Download URL | bingoviewer-2.13.0-py3-none-any.whl |
|---|---|
| Size | 181.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e73bfb19ed4006b49c7d08db70660d2227dc97b466603734f5d27d461b2c30f6
|
|
BLAKE2b-256 checksum How to use checksums |
42bf4ac9e96a1e60020852213d1bdadd893171617d459861d4c7d906c3632174
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jul 29, 2026.
Transparency log
