Skip to content
Joel Natividad edited this page Nov 15, 2026 · 20 revisions

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 77–78 prebuilt (macOS / x86_64 Linux) full A per-platform feature list (see the note below), including get; a source build with -F all_features adds get_cloud, clipboard and more Day-to-day workstation use; the default
qsvpy311/312/313/314 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. The counts come from running --list on the official prebuilts: qsv (77), qsvmcp (70) and qsvlite (51) on aarch64-apple-darwin; qsv (78), qsvmcp, qsvlite and qsvdp (43) on x86_64-unknown-linux-gnu. qsvdp is not shipped for macOS.

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 leaves out get_cloud and geoconnex; it also leaves out ui (clipboard) on macOS, Windows x86_64 and Linux x86_64/ARM64 (GNU and musl); only the Windows ARM64 (msvc and gnullvm), IBM Power (ppc64le) and IBM Z (s390x) builds include it. The aarch64-apple-darwin qsv lists 77 commands (no clipboard or prompt; applydp and py belong to qsvdp/qsvpy*); x86_64 Linux's feature list adds prompt (78, 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. The prebuilt qsv includes get, so qsv get and dc: inputs work on every platform; cloud sources (s3://, gs://, az://) need qsvdp or a source build with -F get_cloud (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

qsvlite does not bundle the describegpt command. Use the full qsv variant if you need describegpt.

Note

viz is 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 and its inverse writestat are both 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

qsvmcp has no get command, accepts no dc: disk-cache-prefix inputs, and reads no cloud (s3://, gs://, az://) sources. qsvdp and source builds with the get_cloud feature have full cloud support (the prebuilt qsv has plain get but no cloud sources; see the note under the matrix). Within qsvmcp, the http(s)://, dathere:// and ckan:// schemes work, as does auto-decompression of compressed sources. See Get & Disk Cache and MCP Server.

The qsvpy builds carry qsv's feature set (including viz) plus python, except get.

CPU requirements and prebuilt targets

Warning

The x86_64 prebuilts target 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. See Installation.

Getting Illegal instruction (SIGILL) on an old x86_64 CPU? On a CPU without AVX2 it is expected: use qsvdp, a 23.0.x release (the last without the AVX2 requirement), or build from source (cargo build --release --bin qsv -F all_features, which defaults to the portable baseline). ARM64 / IBM Power / s390x are unaffected.

There are no "portable" qsvp* binaries (qsvp, qsvplite, qsvpdp, qsvpmcp) in any release archive. If a script, installer or bookmark expects one, use the regular binary of the same variant (qsvp → qsv, qsvplite → qsvlite, qsvpdp → qsvdp, qsvpmcp → qsvmcp).

target-cpu=native is used only on targets built on matching hardware — Apple Silicon (.cargo/config.toml's [target.aarch64-apple-darwin]), Windows-on-ARM, ppc64le and s390x.

Note

ARM64 prebuilt targets: aarch64-unknown-linux-gnu, aarch64-unknown-linux-musl, aarch64-pc-windows-msvc and aarch64-pc-windows-gnullvm (#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.

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 / qsvpy314 (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

Home · Why qsv? · Tier legend

Quick links

Get Started

Command Reference

Cookbook

Tuning & Internals

Ecosystem

Reference

Legacy

Clone this wiki locally