Binary Variants - dathere/qsv GitHub Wiki

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 76–77 prebuilt (macOS / x86_64 Linux) full A per-platform feature list (see the note below); a source build with -F all_features adds get, clipboard and more Day-to-day workstation use; the default
qsvpy311/312/313 qsv + py full + Python Same as qsv plus the Python feature (dynamically linked) — adds py When you need qsv py or Python expressions for transformations
qsvmcp 70 smaller feature_capable, geocode, mcp, polars, profile, readstat, self_update, synthesize, to, viz 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 43 ~16 % of qsv DataPusher+ optimized: embedded luau, slim applydp, no progress bar, --update-gated self-update DataPusher+ CKAN pipelines

Each figure includes the built-in help command. 24.0.0 adds one command, writestat, which ships wherever readstat does (qsv, qsvpy*, qsvmcp). The qsvmcp (70) and qsvlite (51) counts were checked by running --list on the official 24.0.0 aarch64-apple-darwin prebuilt; qsvdp is not shipped for macOS and keeps its 23.0.1 count.

[!NOTE] The prebuilt qsv doesn't have every command. qsv has 80 commands across all its variants (the README table). The release workflows build qsv from an explicit, per-platform feature list that has never included get or geoconnex, and on macOS and x86_64 doesn't include ui (clipboard). The official 24.0.0 aarch64-apple-darwin qsv lists 76 commands (no get, clipboard, prompt; applydp and py belong to qsvdp/qsvpy*); x86_64 Linux's feature list adds prompt (77, from the workflow, not a run). Other platforms vary — e.g. the Windows ARM64 builds use a smaller list that does include ui. Run qsv --list to see what your binary has. For get and dc: inputs, use qsvdp or build qsv with -F get (Get & Disk Cache).

qsvmcp omits the 10 commands MCP doesn't need — apply, clipboard, color, fetch, fetchpost, foreach, get, 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* (both as viz_static, which adds PNG/SVG/PDF/JPEG/WebP export) and qsvmcp (as plain viz — viz over MCP is HTML-only by design, so the browser-backed static-export path was never reachable there), 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.

[!NOTE] readstat first ships in 23.0.1, and its inverse writestat in 24.0.0 — both are in qsv, qsvpy* and qsvmcp, but not in qsvlite or qsvdp. It rides on polars, so like viz it is absent from the big-endian targets (s390x, ppc64 BE). See Conversion & I/O.

[!WARNING] Breaking for qsvmcp users in 23.0.1: qsvmcp no longer ships the get command, no longer accepts dc: disk-cache-prefix inputs, and no longer reads cloud (s3://, gs://, az://) sources. qsvdp and source builds with the get_cloud feature keep full cloud support (the prebuilt qsv never included get; see the note under the matrix), and within qsvmcp the http(s)://, dathere:// and ckan:// schemes are unaffected — as is auto-decompression of compressed sources. See Get & Disk Cache and MCP Server.

Portable subvariants — retired in 22.0.1

[!IMPORTANT] The "portable" binaries (qsvp, qsvplite, qsvpdp, qsvpmcp) are no longer published. They were dropped in 22.0.1 and publish-portable.yml was deleted. If you have a script, installer or bookmark that expects a qsvp* binary inside a release archive, it will not find one — use the regular binary of the same variant instead (qsvp → qsv, qsvplite → qsvlite, qsvpdp → qsvdp, qsvpmcp → qsvmcp).

They existed as a SIGILL fallback "compiled without any CPU features enabled" — but -C target-cpu=native was removed from the x86_64 publish targets long before, precisely because it caused SIGILL on GitHub runners. The regular prebuilt binaries have been equally portable ever since. target-cpu=native survives only on targets built on matching hardware — Apple Silicon (.cargo/config.toml's [target.aarch64-apple-darwin]), Windows-on-ARM, ppc64le and s390x — and the portable workflow built none of those, so across all five targets it did build (x86_64 Linux gnu/musl, x86_64 Windows msvc/gnu, aarch64 Linux) there was no CPU-feature difference to speak of.

Reading the central directory of the 22.0.1 Linux archive confirmed it: qsvplite and qsvpdp matched qsvlite/qsvdp byte-for-byte, qsvpmcp matched qsvmcp's size, and only qsvp differed from qsv — because qsv is PGO-optimized and qsvp was not, an optimization difference rather than a portability one. Removing them took 4 entries and ~434 MB of uncompressed payload out of the archive, shrinking the published zip from 479 MB to 335 MB.

Getting Illegal instruction (SIGILL) on an old x86_64 CPU? Through 23.0.x the regular binary was the portable one, so a SIGILL was a genuine bug. From 24.0.0 the x86_64 prebuilts require AVX2 (see below), so on a CPU without it a SIGILL is expected: use qsvdp, a 23.0.x release, or build from source (cargo build --release --bin qsv -F all_features, which still defaults to the portable baseline). ARM64 / IBM Power / s390x are unaffected.

[!WARNING] Breaking in 24.0.0: the x86_64 prebuilts moved from the baseline to x86-64-v3 and require AVX2/FMA/BMI2 (#4649) — qsv, qsvlite, qsvmcp, qsvpy*, the .deb and the MCPB bundle. qsvdp is the one x86_64 variant that stays portable, since DataPusher+ servers often run on VMs without AVX2. On a non-AVX2 CPU a SIGILL from the other variants is expected rather than a bug. See Installation.

[!NOTE] New prebuilt targets in 24.0.0: Linux ARM64 musl (aarch64-unknown-linux-musl) and Windows ARM64 GNU-family (aarch64-pc-windows-gnullvm), joining the existing aarch64-unknown-linux-gnu and aarch64-pc-windows-msvc builds (#4721, #4722). The Linux ARM64 musl build uses the reduced feature set of the x86_64 musl build and the system allocator, and — like aarch64-unknown-linux-gnu — ships no qsvdp or qsvmcp. The gnullvm binaries link libunwind/libc++ statically, so they need only Windows system DLLs.

[!NOTE] As of 22.0.1, the qsvpy builds carry the same feature set as qsv (including viz). Previously they were built from a narrower feature list, so a 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