Repository navigation
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.
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)
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
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 qsvAlternatively, 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 theluaufeature 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 noqsvdp/qsvmcp) -
linux-powerpc64le-gnu— IBM Power servers (CPU optimizations enabled) -
s390x-unknown-linux-gnu— IBM Z mainframes (CPU optimizations enabled; from the releases page)
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_featuresApple 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.
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.keyPrebuilt binaries include the self_update feature, so you can update in place:
qsv --updateself_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.
# 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::qsvHeads 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.
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 qsvNote
The qsv Debian package is built for x86-64-v3 and requires AVX2 (see above). The qsvdp package stays on the portable baseline.
If you have Rust installed:
cargo install qsv --locked --features all_featuresThis 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.
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,foreachOther 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_plusThe 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.
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.jsonSee AI & Documentation for details.
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.
qsv --version
qsv --list # shows all available commandsYou'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
- README installation section — source of truth
-
docs/FEATURES.md— feature flag matrix - Binary Variants
- Troubleshooting
- qsv pro Spotlight
qsv — GitHub · Releases · Discussions · crates.io · qsv pro · Try it online · Benchmarks · DeepWiki · DOI · Licensed MIT · Third-party notices · AI Policy
qsv was made possible by datHere: standards-based, best-of-breed, open source solutions to make your Data Useful, Usable & Used.
Edit this page: Contributing to the Wiki
Home · Why qsv? · Tier legend
- Whirlwind Tour · Notebooks · Lessons & Exercises
- Benchmarks · Interactive Benchmarks
- Visualizations Gallery
- Neuro-symbolic, Localizable, Data Schematics
- Feature Flags · Goals/Non-goals · Testing
- Talks: NYC SOD 2022 · csv,conf,v8 · PyCon US 2025 · csv,conf,v9 · NYC SOD 2026
- "Have we achieved ACI?" series: 1 · 2 · 3 · 4
- Sponsor
- All Commands (index)
- Selection & Inspection
- Transform & Reshape
- Aggregation & Statistics
- Joins & Set Ops
- SQL & Polars
- Validation & Schema
- Metadata Profiling (profile)
- Conversion & I/O
- Geospatial
- Visualization (viz)
- HTTP & Web
- Get & Disk Cache
- Scripting (Luau / Python)
- Indexing, Compression & Diff
- AI & Documentation
- Recipes index
- Inspect an Unknown CSV
- Clean & Normalize
- Geographic Enrichment
- Date Enrichment
- CKAN Integration
- DCAT-US v3 for data.gov
- JSON Schema Validation
- Round-Trip SAS / Stata / SPSS
- Build a Data Pipeline
- Stats → Insights
- Data-Quality Signals with moarstats
- Group By
- Fetch & Cache
- Larger-than-RAM CSV
- Diff & Audit
- Multi-table Joins
- Synthesize Fake Data
- Performance Tuning
- Benchmarks
- Tuned csv Fork Benchmarks
- Security & Dependency Audits
- Environment Variables
- Stats Cache & Caching
- Lookup Tables
- MiniJinja Templating