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

Installation

Tier: Beginner

This page covers the five ways to install qsv. For the absolute fastest path, download a prebuilt binary (Option 1). For a graphical alternative, see qsv pro.

Note

Looking for the MCP server or Claude Cowork plugin? Those are separate installations described in the qsv MCP Server Getting Started guide. See also MCP Server and Claude Cowork Plugin.

Tip

Running qsv from Python? Use qsv-client (pip install qsv-client). It stops qsv and every process qsv started on a timeout, raises typed exceptions instead of making you parse stderr, and reports the installed binary's version, features and commands. It has sync and asyncio clients and no runtime dependencies. qsv itself is not bundled: install qsv with one of the options below.

Option 0 — qsv pro (GUI)

Prefer a graphical interface? qsv pro is the GUI companion to qsv: drop a spreadsheet and explore it interactively. Available for Windows, macOS, and Linux. See qsv pro Spotlight for what it adds over the CLI.

Download: Windows · macOS · Linux (deb) · Linux (rpm) · Linux (AppImage)

Option 1 — Prebuilt binaries (fastest)

Full-featured prebuilt binaries for Linux, macOS, and Windows ship with every release. They include all features except Python (use qsvpy* variants for Python).

The macOS Apple Silicon, Linux x86_64 (GNU), Linux ARM64 (GNU) and Windows x86_64 (MSVC) prebuilts are Profile-Guided-Optimization (PGO) tuned for extra performance out of the box — no action required. Apple Silicon, Windows on ARM, IBM Power (ppc64le) and IBM Z (s390x) prebuilts also have CPU optimizations enabled (target-cpu=native); x86_64 prebuilts target x86-64-v3 (see below). Releases also include binaries built with Rust nightly. See Performance Tuning → PGO-optimized prebuilt binaries.

The prebuilt qsv and qsvpy* binaries also include the viz command (with static PNG/SVG/PDF export) on the little-endian targets. See Binary Variants.

Download from the latest release, or get your platform's ZIP directly: Linux x86_64 GNU · Linux AArch64 GNU · Linux x86_64 MUSL · Linux PowerPC64 LE · macOS (Apple Silicon) · Windows MSVC · Windows AArch64 MSVC · Windows GNU

Platform-specific notes

macOS — binaries are signed with an ad-hoc signature. The first time you run qsv, macOS may quarantine it. Remove the quarantine attribute:

# Replace qsv with qsvmcp, qsvlite, qsvdp or qsvpy* if installing those variants
sudo xattr -d com.apple.quarantine qsv

Alternatively, use Gatekeeper settings to allow the binary.

Windows — A one-click MSI Easy Installer is available. Download qsv-easy-installer_1.1.2_x64_en-US.msi (all releases) and run it, then click Install qsv inside the installer. It downloads the latest qsv and adds it to your PATH.

Important

Use Easy Installer v1.1.2 or later — then confirm with qsv --version.

Installer versions at or below v1.1.1 extract a hardcoded qsvp.exe, a portable binary that releases don't include. Because the installer's update path returns no error, it shows you a "Successfully installed qsv" message regardless.

The symptom is not a crash but an absence: qsv goes missing from your PATH, or silently stays at its old version. If that already happened, install v1.1.2+ and re-run it, or download the x86_64-pc-windows-msvc archive and extract qsv.exe yourself.

Windows on ARM — besides aarch64-pc-windows-msvc, there is aarch64-pc-windows-gnullvm, which links libunwind/libc++ statically and needs only Windows system DLLs.

Linux — pick the variant matching your libc:

  • linux-x86_64-gnu — most distros (Ubuntu, Debian, Fedora, Arch)
  • linux-x86_64-musl — Alpine, Void Linux, statically-linked deployments. Note that the luau feature is not available in musl builds (see Troubleshooting)
  • linux-aarch64-gnu — ARM64 Linux (Raspberry Pi 4/5, AWS Graviton, Apple Silicon under Linux)
  • linux-aarch64-musl — ARM64 Alpine / static deployments (reduced feature set like x86_64 musl, and no qsvdp/qsvmcp)
  • linux-powerpc64le-gnu — IBM Power servers (CPU optimizations enabled)
  • s390x-unknown-linux-gnu — IBM Z mainframes (CPU optimizations enabled; from the releases page)

SIGILL ("Illegal instruction") on x86_64?

Warning

x86_64 prebuilts require a CPU with AVX2, FMA and BMI1/BMI2 (x86-64-v3, #4649). This covers qsv, qsvlite, qsvmcp and qsvpy* on Linux (gnu and musl) and Windows (msvc and gnu), plus the Debian package and the MCPB bundle. qsvdp is exempt and stays on the portable baseline, because DataPusher+ servers often run on VMs without AVX2. aarch64, ppc64le and s390x prebuilts are unaffected.

Intel Haswell (2013) / AMD Excavator (2015) and newer qualify, but not every newer machine does: Intel Pentium/Celeron/Atom parts up to ~2020, and VMs with a conservative CPU model (QEMU/Proxmox kvm64/qemu64), lack AVX2. Check with grep -o avx2 /proc/cpuinfo | head -1; no output means no AVX2. On such a CPU those prebuilts die with Illegal instruction — that is expected, not a bug.

Do not run qsv --update on a non-AVX2 CPU. It installs a binary that cannot run, and so cannot update itself back. If that already happened, re-download a 23.0.x release (the last without the AVX2 requirement) from the releases page, or build from source (below), which defaults to the portable baseline:

cargo install qsv --locked --features all_features

Apple Silicon, Windows-on-ARM, IBM Power, and IBM Z mainframe builds always have CPU optimizations enabled (no SIGILL risk).

Note

There are no p-suffixed "portable" binaries (qsvp, qsvplite, qsvpdp, qsvpmcp) in any release archive. See Binary Variants.

Verifying the integrity of prebuilt binaries

All prebuilt zip archives are signed with zipsign:

# Install zipsign (once)
cargo install zipsign

# Download the qsv-zipsign-public.key from
#   https://github.com/dathere/qsv/raw/master/src/qsv-zipsign-public.key
# Then verify
zipsign verify zip qsv-<version>-<target>.zip qsv-zipsign-public.key

Self-update

Prebuilt binaries include the self_update feature, so you can update in place:

qsv --update

self_update fetches only from the official releases page and verifies the zipsign signature automatically.

Warning

x86_64 prebuilts require AVX2 (details). On an x86_64 CPU without AVX2, don't run qsv --update — it installs a binary that can't run, and so can't update itself back. Check first with grep -o avx2 /proc/cpuinfo | head -1.

Running bare qsv with no command also does a background check for a newer release. That check is throttled to twice a month — a timestamp in the qsv cache directory (QSV_CACHE_DIR, else ~/.qsv-cache) records the last check, so day-to-day use doesn't hit the network. Set QSV_NO_UPDATE=1 to opt out entirely; the opt-out is honored before the cache directory is even touched.

Option 2 — Package managers

Packaging status

# Arch Linux (Extra)
pacman -S qsv

# Homebrew (macOS / Linux)
brew install qsv

# MacPorts (macOS)
sudo port install qsv

# Mise (Linux / macOS / Windows)
mise use -g qsv@latest

# Nixpkgs (Linux / macOS)
nix-shell -p qsv

# Scoop (Windows)
scoop install qsv

# Void Linux
sudo xbps-install qsv

# Conda-forge
conda install conda-forge::qsv

Heads up: these distributions are maintained by volunteers and enable different feature sets. For example, Homebrew enables only the apply, fetch, foreach, geocode, lens, luau and to features, but it does install shell completion for bash, fish and zsh automatically. Run qsv --version to see which features are enabled in your install (more info). datHere loosely collaborates with the package maintainers, but these packages are maintained by third parties.

Debian / Ubuntu via datHere APT repo

datHere maintains a Debian package for the latest Ubuntu LTS (x86_64):

wget -O - https://dathere.github.io/qsv-deb-releases/qsv-deb.gpg \
  | sudo gpg --dearmor -o /usr/share/keyrings/qsv-deb.gpg
echo "deb [signed-by=/usr/share/keyrings/qsv-deb.gpg] https://dathere.github.io/qsv-deb-releases ./" \
  | sudo tee /etc/apt/sources.list.d/qsv.list
sudo apt update
sudo apt install qsv

Note

The qsv Debian package is built for x86-64-v3 and requires AVX2 (see above). The qsvdp package stays on the portable baseline.

Option 3 — Cargo install (cargo install qsv)

If you have Rust installed:

cargo install qsv --locked --features all_features

This builds from crates.io. It's slower than downloading the prebuilt binary and lacks self_update. It targets the portable baseline by default, so it runs on x86_64 CPUs without AVX2; add CARGO_BUILD_RUSTFLAGS='-C target-cpu=native' for a binary tuned to your exact CPU.

Option 4 — Compile from source

git clone https://github.com/dathere/qsv.git
cd qsv

# Full-featured
cargo build --release --locked --bin qsv -F all_features

# All CPU optimizations for your CPU (non-portable binary)
CARGO_BUILD_RUSTFLAGS='-C target-cpu=native' \
  cargo build --release --locked --bin qsv -F all_features

# Only the features you need (smaller binary)
cargo build --release --locked --bin qsv -F feature_capable,fetch,foreach

Other variants:

cargo build --release --locked --bin qsvmcp -F qsvmcp        # MCP server
cargo build --release --locked --bin qsvlite -F lite         # ~16% size, xsv-compatible
cargo build --release --locked --bin qsvdp   -F datapusher_plus

The compiled binary lands in ./target/release/. See Binary Variants for when to pick each variant, and Performance Tuning for nightly builds.

You'll need a C linker:

  • Ubuntu/Debian: sudo apt install build-essential
  • macOS: xcode-select --install
  • Windows: Visual Studio 2022 with the "Desktop Development with C++" workload, the Windows SDK, and the English language pack

The feature_capable, qsvmcp, lite, and datapusher_plus features are mutually exclusive — see docs/FEATURES.md for the full feature flag matrix.

Tool definitions

qsv and qsvmcp can describe their own commands in machine-readable form for agents and other tools, generated from the installed binary's usage text so they always match its version and feature set:

qsv stats --help --format json        # one command's JSON tool definition
qsv stats --help --format md          # its help as Markdown
qsv --export-tool-definitions defs    # all installed commands, plus a manifest.json

See AI & Documentation for details.

Shell completion

qsv supports completion in bash, zsh, powershell, fish, nushell, fig, and elvish. Download the script for your shell — bash · zsh · PowerShell · fish · nushell · fig · elvish — or, for Bash, follow the step-by-step tutorial at 100.dathere.com.

To customize completions, see contrib/completions/README.md.

Verify the install

qsv --version
qsv --list      # shows all available commands

You're ready! Next:

See also

Home · Why qsv? · Tier legend

Quick links

Get Started

Command Reference

Cookbook

Tuning & Internals

Ecosystem

Reference

Legacy

Clone this wiki locally