fqc

fqc is a Rust FASTQ compressor built around a block-indexed .fqc archive format. It combines a short-read ABC-style path, Zstd-backed medium/long-read compression, and quality-score coding into a single CLI for compression, decompression, inspection, and verification.

Why use it

• FASTQ-aware archive format instead of a generic compressed blob
• Block-level metadata for inspection, verification, and partial workflows
• Single binary CLI with compress, decompress, info, and verify
• Memory-safe Rust implementation with a pinned MSRV of 1.75.0

Installation

Download release binaries from the GitHub Releases page, or build locally:

cargo build --release
cargo install --path .

Quick start

git clone https://github.com/LessUp/fq-compressor-rust.git
cd fq-compressor-rust
cargo build --release

./target/release/fqc compress -i tests/data/test_se.fastq -o sample.fqc
./target/release/fqc info -i sample.fqc
./target/release/fqc verify -i sample.fqc
./target/release/fqc decompress -i sample.fqc -o sample.fastq

Common commands

fqc compress -i reads.fastq -o reads.fqc
fqc compress -i reads.fastq -o reads.fqc --memory-limit 0
fqc compress -i reads.fastq -o reads.fqc --pipeline
fqc compress -i reads.fastq -o reads.fqc --streaming
fqc compress -i reads.fastq -o reads.fqc --streaming --memory-limit 1024
fqc compress -i reads_R1.fastq -2 reads_R2.fastq -o paired.fqc

fqc decompress -i reads.fqc -o reads.fastq
fqc decompress -i reads.fqc -o subset.fastq --range 1:1000
fqc decompress -i reads.fqc -o reads.fastq --original-order
fqc decompress -i paired.fqc -o paired.fastq --split-pe

fqc info -i reads.fqc --detailed --show-codecs
fqc verify -i reads.fqc
fqc verify -i reads.fqc --quick

Documentation

The maintained docs summary lives in the docs site and repo-backed docs pages below.

• Project site: https://lessup.github.io/fq-compressor-rust/
• Quick start: docs/guide/quick-start.md
• CLI reference: docs/guide/cli.md
• Architecture overview: docs/architecture/index.md
• Performance roadmap: docs/architecture/performance-roadmap.md
• Algorithms: docs/algorithms/index.md

--memory-limit 0 keeps the default automatic memory selection behavior. For strict low-memory runs, prefer --streaming; pipeline mode remains a staged execution path, and archive mode still performs a full ingest for global analysis.

Development

This repository uses OpenSpec as its planning and change-management layer.

• living specs: openspec/specs/
• active change folders: openspec/changes/
• AI contributor guide: AGENTS.md

Validation commands:

cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test --lib --tests
cargo doc --no-deps
npm run docs:build

To enable local Git hooks:

bash scripts/setup-hooks.sh