Installation¶

Prerequisites¶

VNtyper 2 requires the following external tools on your system:

Dependency	Minimum Version	Purpose
Python	3.10+	Core runtime
Java	11+	Kestrel genotyping engine
BWA	0.7.18+	Read alignment
samtools	1.20+	BAM/CRAM manipulation
fastp	0.23+	FASTQ quality control

External tools required

External tools (BWA, samtools, fastp, Java 11) must be installed separately when using pip or source installation. The Docker image and Conda environment bundle all dependencies.

Install VNtyper 2¶

CondaDockerpipFrom Source

Use the provided environment file to create a Conda environment with all dependencies (including external binaries):

git clone https://github.com/hassansaei/vntyper.git
cd vntyper

# Create the environment
conda env create -f conda/environment_vntyper.yml
conda activate vntyper

# Install VNtyper 2 into the environment
pip install -e .

environment_vntyper.yml pins Python 3.12.13 and includes BWA, samtools, fastp, OpenJDK 11, and all Python dependencies. That pin matches what the Docker image runs; the package itself declares requires-python = ">=3.10", and CI tests 3.10 through 3.13.

Additional environment files are available for optional modules:

conda/environment_envadvntr.yml: adVNTR genotyping module
conda/environment_shark.yml: SHARK read filtering module

Pull the current image from GitHub Container Registry:

docker pull ghcr.io/hassansaei/vntyper:latest

Released images are published to GHCR as latest (the newest release), the immutable vX.Y.Z and X.Y.Z tags naming one exact release, and the moving X and X.Y series tags. Pin vX.Y.Z for a reproducible run. The main tag is rolling and tracks the default branch. Docker Hub artifacts are legacy, frozen, and unsupported.

Or build from source:

git clone https://github.com/hassansaei/VNtyper.git
cd VNtyper
DOCKER_BUILDKIT=1 docker build -f docker/Dockerfile -t vntyper:latest .

Install directly from GitHub:

pip install git+https://github.com/hassansaei/VNtyper.git

Clone the repository and install in editable mode:

git clone https://github.com/hassansaei/vntyper.git
cd vntyper
pip install -e .

Install the References¶

Conda and source installations need the reference bundle before vntyper pipeline can run. Install it into reference/ from the repository root:

cd vntyper
vntyper install-references -d reference

Run the pipeline from the repository root

Every tool and reference path in the shipped vntyper/config.json is relative to the directory you run vntyper from: ./vntyper/dependencies/kestrel/ for the Kestrel JARs and ./reference/ for the references. On a cluster, cd into the checkout at the top of the job script. When you upgrade by cloning a new version into a new directory, install the references there too. If a file is missing, the pipeline stops before reading any input and prints the path it tried. See Troubleshooting.

The Docker image ships with the references installed. See Reference Setup for assemblies beyond hg19/hg38.

Verify Installation¶

Confirm VNtyper 2 is installed correctly:

vntyper --version

Development Install¶

To install with development dependencies (Ruff linter, pytest, mypy):

git clone https://github.com/hassansaei/vntyper.git
cd vntyper
pip install -e .[dev]

Run the test suite to verify everything works:

make test-unit

See the Contributing Guide for full development setup instructions.