Binary Variants

Binary Variants

Tier: Intermediate

qsv ships five binary variants. They share most code but differ in feature set, size, and intended use. Pick the right variant for your environment.

TL;DR: Use qsv (full) on your workstation. Use qsvlite if you're migrating from xsv or want a tiny install. Use qsvdp inside a DataPusher+ CKAN pipeline. Use qsvmcp to expose qsv as an MCP server. Use qsvpy* if you need the Python feature.

The matrix

Variant	Approx. size	Features	Use case
qsv	full	All feature flags applicable to prebuilt builds (except Python)	Day-to-day workstation use; the default
qsvpy311/312/313	full + Python	Same as qsv plus the Python feature (dynamically linked)	When you need qsv py or Python expressions for transformations
qsvmcp	smaller	geocode, luau, mcp, polars, self_update, to	Running qsv as a Model Context Protocol server for Claude / other MCP clients
qsvlite	~16 % of qsv	None of the optional features	xsv migrants; minimal CI installs; low-memory environments
qsvdp	~16 % of qsv	DataPusher+ optimized: embedded luau, slim applydp, no progress bar, --update-gated self-update	DataPusher+ CKAN pipelines

The feature_capable, qsvmcp, lite, and datapusher_plus features are mutually exclusive at compile time. You build one binary variant per build.

Portable subvariants (SIGILL fix)

Each variant has a "p for portable" subvariant compiled without CPU-specific optimizations:

Subvariant	Built from
qsvp	qsv
qsvplite	qsvlite
qsvpdp	qsvdp

Use a portable subvariant if you get Illegal instruction (SIGILL) errors on older x86_64 CPUs. ARM64 / IBM Power / s390x always have CPU optimizations enabled (no SIGILL risk).

Choosing a variant — decision tree

Are you migrating from xsv and want a drop-in replacement?
├── Yes → qsvlite
└── No
    │
    Are you embedding qsv inside DataPusher+ / CKAN?
    ├── Yes → qsvdp
    └── No
        │
        Are you exposing qsv as an MCP server to an LLM client?
        ├── Yes → qsvmcp
        └── No
            │
            Do you need `qsv py` (Python expressions)?
            ├── Yes → qsvpy311 / qsvpy312 / qsvpy313 (match your Python install)
            └── No → qsv (the default)

Migrating from xsv

qsvlite preserves xsv's command set and CLI ergonomics. Aliases:

mv qsvlite xsv     # if you want the same binary name
xsv stats data.csv

Or keep both:

xsv stats data.csv     # original xsv behavior
qsvlite stats data.csv # same thing, more modern
qsv stats data.csv     # full-featured: 47 stats vs xsv's 12

See Comparison vs others for a feature-by-feature comparison and the xsv vs qsv stats wiki page for the stats column count breakdown.

Variant feature matrix

For the exact set of features each variant ships, run:

qsv --version

The output includes the version, the feature list, and the upstream library versions (Polars, jemalloc, etc.). See docs/PERFORMANCE.md#version-details for how to interpret the output.

For the canonical feature-flag list and how to compile each variant from source, see docs/FEATURES.md and the Installation → Compile from source section.

Variant-specific commands

A few commands are variant-specific by design:

Command	Available in	Why
apply	qsv, qsvpy*, qsvmcp	Full NLP / date / currency suite
applydp	qsvdp only	Slim version of apply for CKAN; trim, safen, cast
lens, clipboard, prompt	UI feature group: qsv, qsvpy*	Interactive / desktop-only
mcp	qsvmcp only	MCP server entry point
py	qsvpy* only	Python is dynamically linked to a specific 3.x version
pro	qsv, qsvpy*	Bridges to the qsv pro API

For the full mapping, see docs/FEATURES.md.

See also

• Installation
• docs/FEATURES.md — feature flag matrix (canonical)
• docs/INTERPRETERS.md — Python / Luau build details
• MCP Server — qsvmcp deployment
• qsv pro Spotlight — graphical companion
• Integrations — DataPusher+, CKAN, DuckDB, Python notebooks