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.

Tip

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

Counts verified against qsv 22.0.1. qsvmcp omits the 9 commands MCP doesn't need — apply, clipboard, color, fetch, fetchpost, foreach, lens, luau and prompt.

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

Note

As of 21.1.0, qsvlite no longer bundles the describegpt command — removing it trims the binary by ~4 MB. Use the full qsv variant if you need describegpt.

Note

viz first ships in 22.0.1 — it's in qsv, qsvpy* and qsvmcp (as viz_static, which adds PNG/SVG/PDF/JPEG/WebP export), but not in qsvlite or qsvdp. It is enabled across the little-endian publish targets only: viz is unsupported on big-endian (s390x, ppc64 BE) and is a hard compile_error! there rather than a silently broken binary. See Visualization.

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).

Note

As of 22.0.1, the portable and qsvpy builds carry the same feature set as their parent variant (including viz). Previously they were built from a narrower feature list, so a qsvp/qsvpy binary could quietly lack features the release notes advertised.

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: 48 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*	Full NLP / date / currency suite (the standalone apply feature; not in qsvmcp, which ships feature_capable but not apply)
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