Installation

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.

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.

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.

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

Download from the latest release, or browse by platform at qsv.dathere.com/download.

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, or qsvdp if installing those variants
xattr -d com.apple.quarantine qsv

Alternatively, use Gatekeeper settings to allow the binary.

Windows — A one-click MSI Easy Installer is available for the portable qsvp (x86_64 MSVC) binary. Download the qsv-easy-installer_*.msi and run it, then click Install qsv inside the installer. It downloads the latest qsvp and adds it to your PATH.

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-powerpc64le-gnu — IBM Power servers (CPU optimizations enabled)

SIGILL ("Illegal instruction") on x86_64?

Older x86_64 CPUs can crash with SIGILL when the binary uses an instruction the CPU doesn't support. Every release also includes portable variants compiled without CPU-specific optimizations — they have a p suffix:

• qsvp (full-featured, portable)
• qsvplite (lite, portable)
• qsvpdp (datapusher_plus, portable)

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

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.

Option 2 — Package managers

# 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 apply, fetch, foreach, geocode, lens, luau, and to but not all of them. Run qsv --version to see which features are enabled in your install.

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

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, but it produces a binary matching 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.

Shell completion

qsv supports completion in bash, zsh, powershell, fish, nushell, fig, and elvish. Download the script for your shell from qsv.dathere.com/download or 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:

• Getting Started — first commands against a real 2.7M-row dataset
• Binary Variants — qsv vs qsvlite vs qsvdp vs qsvmcp
• Troubleshooting — Gatekeeper, SIGILL, UTF-8, and other gotchas

See also

• README installation section — source of truth
• docs/FEATURES.md — feature flag matrix
• Binary Variants
• Troubleshooting
• qsv pro Spotlight