Setup guide

Install once, then run repeatable genome workflows.

WGS Extract CLI v0.6.6 uses Pixi to manage Python, the app itself, and many external bioinformatics tools. macOS and Linux use the standalone terminal installer; Windows uses install_windows.bat from PowerShell, which installs native Windows builds of the tools through Pixi. Linux x86_64 and native Linux ARM64 both use the terminal installer.

macOS/Linux Running the CLI Windows Developer Pixi setup Platforms References Download checks Configuration Verify

Open Terminal first

Open the Terminal app on your machine. On macOS, use Applications > Utilities > Terminal. On Linux, open your normal terminal window.

Paste the installer command

Copy the one-line installer below, paste it into Terminal, and press Enter. The installer prints each step before it runs it.

Use the standalone folder

The installer resolves the latest published GitHub release (not the main branch) and installs it into wgsextract-cli/. The app lives in app/, Pixi files live in .pixi/, installer temp files live in app/tmp/, and the CLI launcher sits beside app/ at wgsextract. On macOS, the installer checks for the Xcode Command Line Tools first and opens this folder in Finder when it finishes.

Bootstrap references

Download the metadata and reference-library structure WGS Extract uses to find FASTA, VCF, ploidy, liftover, and annotation assets.

Run a small test

Use info and region-limited commands first. Whole-genome jobs can take hours and hundreds of gigabytes of working space.

macos-linux.sh

# 1. Open Terminal.
# 2. Paste this line and press Enter.
# 3. The installer creates ./wgsextract-cli.
curl -fsSL https://raw.githubusercontent.com/WGSExtract/wgsextract-cli/main/install.sh | sh

# Put the launcher on PATH for this shell (see "Running the CLI")
export PATH="$PWD/wgsextract-cli:$PATH"

# Initialize reference library data
wgsextract ref bootstrap
wgsextract ref library --list
wgsextract ref library --install hs38

# Verify the environment (exits 1 if a mandatory tool is missing)
wgsextract deps check

# Uninstall the app if needed. Interactive runs ask whether to remove Pixi too.
./wgsextract-cli/uninstall.sh

Running the CLI

Commands on this site are written as plain wgsextract. Use the form that matches how you installed it.

Install type	How to run	Notes
Standalone installer (macOS/Linux)	`./wgsextract-cli/wgsextract`, or `wgsextract` after adding `wgsextract-cli/` to `PATH`	Relative paths resolve against your current directory.
Windows installer or source checkout	`pixi run wgsextract`, from the project folder
Specialized Pixi environments	`pixi run -e pacbio wgsextract ...` (also `vep`), from the app or project folder	See Pixi environments.

To keep the standalone launcher on PATH, add export PATH="/path/to/wgsextract-cli:$PATH" to your shell profile.

Windows native installer

Use the Windows installer from a normal Windows PowerShell window. The tools run natively on Windows, on your Windows files, without WSL or MSYS2.

Run the BAT installer

Open PowerShell on Windows, then move into the WGS Extract CLI folder you cloned or downloaded and run install_windows.bat. If Pixi is missing, the installer installs it first.

What it does

install_windows.bat installs Pixi if needed, then the default and GATK environments: Python, the CLI, and native Windows tools, including samtools, bcftools, BWA, bwa-mem2, minimap2, fastp, samblaster and GKL acceleration for GATK. It finishes with wgsextract deps check.

install_windows.bat

# Open PowerShell in the downloaded wgsextract-cli folder.
# If you have not downloaded the project yet:
git clone https://github.com/WGSExtract/wgsextract-cli.git
cd wgsextract-cli

# Recommended Windows install path: run the BAT installer.
.\install_windows.bat

# If Pixi was just installed, reopen PowerShell first.
# Verify the tools.
pixi run wgsextract deps check

# Uninstall the app-local environment and config defaults.
.\uninstall_windows.bat

# Also remove the Pixi the installer set up.
.\uninstall_windows.bat --remove-prerequisites

Windows prerequisites: Download the repository or clone it with Git, then run the BAT installer; it downloads Pixi when missing. Reopen your shell after a first Pixi installation. Older installs used MSYS2, which is no longer needed. See the Windows guide for details.

Developer Pixi setup

From a source checkout, run the developer setup script once. It requires Git (plus Xcode Command Line Tools on macOS), installs Pixi and just for your user when missing, installs locked default/dev environments and pre-commit hooks, and runs version, dependency and smoke checks.

Best for contributors

Use this path when you plan to edit code, run tests, inspect package metadata, or switch branches frequently.

Same toolchain

The standalone installer still uses Pixi underneath. Developer setup adds contributor tools; optional environments remain explicit installs, not feature-time downloads.

developer-pixi.sh

# macOS/Linux
git clone https://github.com/WGSExtract/wgsextract-cli.git
cd wgsextract-cli
./scripts/dev_setup.sh

# Windows PowerShell, from the checkout:
powershell -ExecutionPolicy Bypass -File scripts\dev_setup.ps1

# Reopen the terminal if Pixi or just was newly installed.
pixi run wgsextract help
just check

Contributor tooling (pytest, ruff, mypy) lives in the dev Pixi environment. Tasks such as pixi run test, pixi run lint, and pixi run typecheck select it automatically. Rerun setup safely, or use just setup once just is available. See Developer setup for skip-test options and the contribution workflow.

Platform notes

Use the standalone installer on macOS/Linux and install_windows.bat on native Windows. On Windows the tools are native Windows programs, so no WSL or MSYS2 setup is needed and they work directly on files on your Windows drives.

macOS

Use the standalone installer. It opens the install folder in Finder and creates the wgsextract CLI launcher.

osx-arm64 osx-64

Linux

Use the standalone installer on x86_64 and on native ARM64 (v0.6.6 and later). ARM64 phase 1 covers CPU alignment, BAM/CRAM, bcftools, microarray exports, coverage, Yleaf/Haplogrep and optional VEP. Native CPU DeepVariant on ARM64 supports WGS only: build localhost/wgsextract-deepvariant:1.10.0-arm64 locally with packaging/deepvariant-arm64/build.sh before calling. Other models and --checkpoint are refused. GATK, Ultima alignment and Parabricks remain gated on Linux ARM64.

linux-64 linux-aarch64 Linux ARM64 scope and validation

Windows

Use install_windows.bat from PowerShell. Pixi installs WGS Extract's own native Windows builds of the bioinformatics tools.

Windows x64 is the published installation path. Windows ARM64 remains an opt-in qualification preview, not part of the default lock or published app artifacts.

win-64 Windows guide

Reference library setup

Most genome operations need a reference genome and companion files. The reference library lets WGS Extract resolve those assets instead of asking you for every path on every command.

Bootstrap data

ref bootstrap initializes the library scaffolding and common metadata. Then use the library commands to list and install supported builds such as hs38.

wgsextract ref bootstrap
wgsextract ref library --list
wgsextract ref library --install hs38

Annotation data comes from ref clinvar, ref gnomad, ref revel, ref phylop, ref gerp, ref spliceai, ref alphamissense, ref pharmgkb, and ref gene-map. ref phylop and ref gerp download one build's per-base scores (about 10 GB each; --build hg19 for hg19). ref spliceai downloads Ensembl's open hg38 scores (28.9 GB); hg19 scores need an Illumina BaseSpace login, so it explains where to put a manually downloaded file.

Index and verify

FASTA references need indexes and dictionaries before alignment and variant callers can use them efficiently.

wgsextract ref index --ref /path/to/hs38.fa
wgsextract ref verify --ref /path/to/hs38.fa
wgsextract ref status

ref verify checks gzip integrity, the FASTA index, and, for catalog genomes, the sequence-dictionary signature; it fails on a mismatch.

Since v0.6.6, the catalog also recognizes and resolves hs38d1c (GRCh38 with additional viral decoys) and hs38d1t (hs38d1s plus MT169739.1). Install the exact model matching the alignment header, not just another hg38 FASTA.

Reference builds matter. hg19/GRCh37, hg38/GRCh38, and T2T coordinates differ. Do not mix BAMs, VCFs, annotation files, and gene coordinates from different builds unless you intentionally lift over or re-run the analysis.

Download verification

Reference bundles are GitHub release assets, versioned separately from app releases so routine releases do not re-upload multi-gigabyte files.

When ref bootstrap, ref library --install, or ref download fetches a GitHub release asset, WGS Extract asks the GitHub Releases API for that asset's sha256:<digest> metadata and verifies the file before extracting or processing it. No neighboring .sha256 files are needed. The native Windows tool packages are pinned by SHA-256 in pixi.toml, which Pixi checks.

If the digest lookup is unavailable (for example, the API is unreachable or rate-limited), WGS Extract logs a warning and continues. Set GITHUB_TOKEN to authenticate the lookup in automation.
If GitHub metadata is fetched but has no valid SHA-256 digest, or the downloaded file does not match it, the download fails.
Reference genomes are checked again after installation: gzip integrity, samtools faidx, and the sequence-dictionary signature.

Configuration

Use wgsextract config to view the active config path and every setting. Set input, output, reference FASTA, reference library, genome library, threads, memory, and external tool paths once instead of repeating them. Command-line options override config values for a single run.

Config locations

macOS: ~/.config/wgsextract/config.toml if ~/.config/ exists, otherwise ~/Library/Application Support/wgsextract/. Linux: ~/.config/wgsextract/config.toml. Windows: %LocalAppData%\theontho\wgsextract\config.toml.

Genome library

Set genome_library to a folder with one subfolder per person or sample. Then --genome sample-id can resolve inputs and outputs from that folder.

config.toml

input = "/data/genomes/joe/joe.cram"
outdir = "/data/genomes/joe/out"
# Reference genome FASTA (same as --ref)
ref = "/data/reference/genomes/hs38.fa.gz"
# Reference library directory
reflib = "/data/reference"
genome_library = "/data/genome-library"
# A number, or "auto"
threads = "auto"
memory = "auto"
haplogrep_path = "/usr/local/bin/haplogrep"

Verify before running full genomes

Start with environment checks and tiny regions. It is much cheaper to catch missing references, unsorted BAMs, or command syntax errors on chrM than halfway through a full-genome job.

verification-recipes.sh

wgsextract deps check
wgsextract --input /data/sample.cram info --detailed
wgsextract --input /data/sample.cram extract mito-vcf
wgsextract --input /data/sample.cram vcf snp --region chrM
wgsextract --input /data/sample.cram microarray --formats 23andme_v5 --region chrM