---
id: cyvcf2
version: "0.34.0"
license: MIT
license_treatment: permissive
maintenance: active
---

# cyvcf2 — fast vcf parsing with cython + htslib

License: permissive · Maintenance: active · Downloads: 217.2K/mo

## What it is and what it does

cyvcf2 is a high-performance Python interface to VCF and BCF genomic variant files, built as a Cython wrapper around the C library htslib. It parses variant records and returns their attributes—chromosome, position, reference and alternate alleles, genotypes, depths, and custom INFO/FORMAT fields—as numpy arrays ready for immediate analysis. The package supports region-based queries on indexed files and works with Python 3.9 and later.

Typical use involves iterating over variants in a file, extracting genotype or depth information as numpy arrays, and filtering or aggregating them downstream. A key design detail is that numpy arrays returned by attributes like `gt_ref_depths` are backed by the underlying C data structure, so they become invalid once the variant object goes out of scope; users must explicitly copy arrays they wish to persist. The package includes a command-line tool for basic VCF inspection and filtering.

Use it for:

- Filter variants by allele frequency or quality thresholds extracted from INFO fields and genotype depths.
- Extract genotype matrices or depth arrays from large VCF files for population genetics or association studies.
- Query specific genomic regions in indexed VCF/BCF files without loading the entire file into memory.
- Convert VCF records to numpy arrays for downstream machine learning or statistical analysis pipelines.
- Rapidly scan VCF files from the command line to inspect headers, sample counts, or variant statistics.

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

cyvcf2 is a Cython wrapper around htslib that parses VCF and BCF genomic variant files at speed, including region-based queries, and returns numpy arrays for immediate downstream analysis.

Yes. cyvcf2 is actively maintained, widely used in bioinformatics, has no known vulnerabilities, and offers permissive licensing. Binary wheels make installation frictionless for most users. Install it if you need to parse VCF or BCF files in Python and want speed and direct numpy integration; avoid it only if you cannot tolerate the C compiler requirement for source builds or the array-lifetime gotcha.

## Install

pip install cyvcf2
uv add cyvcf2
poetry add cyvcf2

## Installing cyvcf2

Before you install: Binary wheels are available for Python 3.9–3.13 on macOS, Linux, and Windows, so most users will install without compilation. Medium friction remains because source builds require htslib and a C compiler; the package is actively maintained with a recent release.

License in practice: MIT license permits commercial and private use with minimal restrictions; you may use, modify, and distribute cyvcf2 freely as long as you include the license notice.

Quickstart:

pip install cyvcf2

from cyvcf2 import VCF

for variant in VCF('some.vcf.gz'):
    print(variant.CHROM, variant.start, variant.REF, variant.ALT)
    dp = variant.format('DP')  # numpy array of depth per sample

Requires htslib >= 1.10 (bundled in wheels); source builds need a C compiler and htslib development headers.

Verify before relying:

- Whether the numpy array backing behavior (arrays becoming invalid when variant goes out of scope) is a practical concern for typical workflows.
- Performance characteristics on very large VCF files or with many concurrent region queries.

## Package facts

- License: MIT (permissive)
- Python support: supports_current
- Install friction: medium
- Maintenance: active
- Downloads: 217.2K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

vcf parsing python, bcf file reader, variant call format, genomic variant parsing, htslib wrapper, region query vcf, fast vcf reader, bioinformatics, genomics, vcf-parsing

[View on SkillFed](https://skillfed.io/packages/cyvcf2) · [View on PyPI](https://pypi.org/project/cyvcf2/)