Quick Start¶

Compress¶

fqxv compress reads.fastq -o reads.fqxv

Gzipped input is detected automatically, and -o is optional — it defaults to the input's name with the FASTQ/gzip extension replaced by .fqxv:

fqxv compress reads.fastq.gz            # writes reads.fqxv

Tune effort with --level (1–9; higher raises the sequence context order — up to order 11, reached at level 5 — then the block size, and enables a hashed high-order tier at level 8+) and threads with --threads (default 16, capped at available cores; 0 = all cores):

fqxv compress reads.fastq.gz -o reads.fqxv --level 7 --threads 16

Not sure how well your data will compress? Add --estimate to predict the archive size and ratio from a sample of the input, writing nothing:

fqxv compress reads.fastq.gz --estimate
# reads.fastq.gz (436.93 MB)  →  estimated fqxv ~216.87 MB  (50% smaller, ~2.01x)

A per-stream breakdown (names / sequence / quality) follows that headline; see compress --estimate for the full report and its accuracy.

Inspect¶

fqxv info reads.fqxv

reads.fqxv
╭────────────────┬─────────────────────────────╮
│ property       │ value                       │
├────────────────┼─────────────────────────────┤
│ layout         │ single-end (group size 1)   │
│ reads          │ 1,000,000                   │
│ blocks         │ 4 (avg 250,000 reads)       │
│ platform       │ Illumina                    │
│ sequence order │ 11                          │
│ quality        │ lossless                    │
│ reordered      │ no                          │
│ plus line      │ normalized                  │
│ format         │ v1.0                        │
│ whole-file crc │ a1b2c3d4                    │
│ file size      │ 46.25 MB (46,254,058 bytes) │
╰────────────────┴─────────────────────────────╯
╭──────────┬────────────┬────────┬────────────╮
│ stream   │      bytes │  share │ bytes/read │
├──────────┼────────────┼────────┼────────────┤
│ names    │  6,189,536 │  13.4% │      6.190 │
│ sequence │ 17,980,884 │  38.9% │     17.981 │
│ quality  │ 22,083,418 │  47.7% │     22.083 │
│ total    │ 46,253,838 │ 100.0% │     46.254 │
╰──────────┴────────────┴────────┴────────────╯
46.25 bytes/read

info reads only the header and footer index, so it does not decode any payload; add --stats for content statistics, or --tsv/--json for scripts. To check an archive's integrity without writing output:

fqxv verify reads.fqxv

Decompress¶

Pick a destination — a file (-o), split mate files (--split), or a stdout stream (-Z). A bare decompress with none of these errors rather than flooding the terminal.

fqxv decompress reads.fqxv -o reads.fastq        # plain FASTQ
fqxv decompress reads.fqxv -o reads.fastq.gz     # block-gzip (BGZF)

Paired-end and single-cell¶

Give multiple inputs to interleave per-spot files into one archive:

fqxv compress sample_R1.fq.gz sample_R2.fq.gz -o sample.fqxv   # paired
fqxv compress R1.fq R2.fq I1.fq I2.fq -o sample.fqxv           # 10x single-cell

Restore the separate files, or stream interleaved straight to an aligner:

fqxv decompress sample.fqxv --split out                  # out_R1.fastq.gz, out_R2.fastq.gz, ...
fqxv decompress sample.fqxv -Z | bwa mem -p ref.fa -     # interleaved, raw, on stdout

--split writes block-gzip .fastq.gz with _R1/_R2 labels by default; add --no-gzip for plain FASTQ or --mate-style num for _1/_2 labels.

Lossy quality (optional)¶

Quality is lossless by default. Opt into binning for smaller archives when you don't need exact quality:

fqxv compress reads.fastq -o reads.fqxv --quality-bin bin8   # or bin4 / bin2

The bin8/bin4/bin2 tables are Illumina-calibrated. Long reads have their own, and the tables are not interchangeable — pick the one matching your platform:

fqxv compress ont_reads.fastq -o ont_reads.fqxv --quality-bin ont    # Nanopore
fqxv compress hifi_reads.fastq -o hifi_reads.fqxv --quality-bin hifi # PacBio HiFi

See Lossy quality binning for what each table costs.