FAQ

FAQ

Tier: Beginner

Note

The evolving Q&A lives in GitHub Discussions → FAQ category. This page collects the questions we hear most often as a quick reference.

Why qsv vs other tools?

Why qsv instead of pandas?

Pandas is in-memory and Python-native. qsv is streaming (for most commands) and shell-native. They serve different needs:

• For sub-second profiling of a multi-GB CSV in a shell or CI step, qsv wins by 10-50×.
• For ad-hoc analytics inside a notebook with charts and ML, pandas wins.
• The two coexist — see Integrations → Python notebooks.

Why qsv instead of DuckDB?

DuckDB is an embedded SQL database. qsv is a CSV-shaped Swiss-army knife. They complement each other:

• qsv to parquet + DuckDB = the gold-standard CSV-to-analytics path
• qsv sqlp runs Polars SQL; qsv scoresql --duckdb lets you analyze a query via DuckDB's planner.
• qsv describegpt with QSV_DUCKDB_PATH uses DuckDB for SQL-RAG.

See Integrations → DuckDB.

Why qsv instead of csvkit?

csvkit was the first serious Python CSV toolkit and is excellent for what it does. qsv is roughly 10× faster on typical workloads (Comparison) (compiled Rust + multithreading) and has many more commands (geocoding, validation, fetch, describegpt, …). If you're already happy with csvkit on small files, no rush — they serve overlapping niches. If you're processing > 100 MB at a time, qsv will save you minutes per run.

Why qsv instead of Miller?

Miller (mlr) is broader (handles TSV, JSON, DKVP, PPRINT, …); qsv is more CSV-specialized with deeper stats and validation. There's significant overlap; pick whichever feels right to your shell muscle memory. Many users use both.

Why qsv instead of xsv?

xsv was BurntSushi's original CSV tool. qsv is a maintained, multithreaded, feature-expanded fork, forked in September 2021 (see the README's Origins and this FAQ). If you're migrating from xsv and want the same experience and feature set, install qsvlite: all feature-gated commands are left out, and it's ~16% of qsv's size. See Binary Variants and Comparison.

Compatibility

Does it work on Windows?

Yes. There's an MSI Easy Installer, Scoop packages, and direct prebuilt downloads. Some notes:

• Unix (\n) and Windows (\r\n) line endings are handled transparently. Set QSV_OUTPUT_BOM=1 for Excel-friendly outputs.
• foreach works best inside Git Bash on Windows.
• clipboard, color, lens and prompt form the UI (🖥️) group and work on Windows. The Windows x86_64 prebuilts include color, lens and prompt but not clipboard (the ui feature); the Windows ARM64 prebuilts include it. qsv pro lens (Windows only) opens csvlens in a new Alacritty window.

See Installation → Windows notes.

What's the Rust MSRV?

Rust 1.99 (bumped for 24.0.0; it was 1.98 for 23.0.1). The MSRV bumps occasionally — check the README badge.

Does it run on ARM (Apple Silicon, Raspberry Pi, AWS Graviton)?

Yes. Prebuilt binaries for aarch64-apple-darwin (macOS), linux-aarch64-gnu, Windows-on-ARM (msvc), and — new in 24.0.0 — aarch64-unknown-linux-musl and aarch64-pc-windows-gnullvm. The Apple Silicon and Windows-on-ARM builds have target-cpu=native enabled; linux-aarch64-gnu is built for the generic ARMv8 baseline so it runs on any 64-bit ARM Linux box. Note that both Linux ARM64 prebuilts use a reduced feature set (no Polars, Luau or viz); run qsv --list to check, or build from source for everything.

Does it run on my older x86_64 CPU?

Only if it has AVX2. From 24.0.0, the x86_64 prebuilts need AVX2/FMA/BMI2 (Intel Haswell 2013 / AMD Excavator 2015 or newer). Some later low-end parts (Pentium/Celeron/Atom up to ~2020) and VMs with a kvm64/qemu64 CPU model lack AVX2. qsvdp is exempt, and a source build still targets the baseline. On a CPU without AVX2, use qsvdp, stay on 23.0.x (whose x86_64 prebuilts target the baseline and run on any 64-bit x86 CPU), or build from source. See Installation.

Does it run on IBM Power / Z mainframes?

Yes. Prebuilt binaries for linux-powerpc64le-gnu and s390x. Both have target-cpu=native enabled.

Concepts

Streaming vs in-memory commands?

Commands marked 🤯 in the README legend load the entire CSV into memory: color, dedup (unless --sorted), pragmastat, readstat, reverse (unless indexed), sort, stats (for advanced metrics), table, transpose and writestat. The README notes that dedup, stats and transpose have "streaming" modes as well.

Everything else streams. For files larger than RAM, use the ext-* companions (extsort, extdedup) and Polars commands (sqlp, joinp, pivotp).

See Performance Tuning → Memory management.

What's an index?

A <file>.idx sidecar that lets random-access commands skip parsing rows they don't need. Build it once (qsv index file.csv); many commands speed up 2-9×. See Indexing, Compression & Diff.

What's the stats cache?

A <file>.stats.csv.data.jsonl sidecar that pre-computes statistics other commands can reuse. The "automagical" (🪄) commands use it to skip work: describegpt, frequency, joinp, pivotp, pragmastat, sample, schema, scoresql, sqlp, stats, tojsonl and viz. See Stats Cache & Caching.

What's "automagical"? (🪄)

Commands with the 🪄 symbol use the stats / frequency caches to work smarter — auto-pick aggregations, short-circuit known-cardinality columns, infer the right JSON type, etc. See docs/PERFORMANCE.md.

Operations

How do I update qsv?

qsv --update

This works for prebuilt binaries (the self_update feature is built in). For package-manager installs, use the package manager's update command.

Warning

From 24.0.0, x86_64 prebuilts require AVX2 (details). On an x86_64 CPU without AVX2, don't qsv --update to 24.0.0 or later — 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.

To disable update checks:

export QSV_NO_UPDATE=1

How do I see what features my qsv has?

qsv --version

The output includes the version, enabled features, and bundled library versions.

How do I see active environment variables?

qsv --envlist

Lists every QSV_* env var plus allocator-specific (MIMALLOC_* / JEMALLOC_* / MALLOC_CONF) and HTTP proxy vars.

Where are logs?

QSV_LOG_DIR (default: directory where qsv was started). Enable with QSV_LOG_LEVEL=info. The MCP server has a separate audit log (qsvmcp.log) controlled by QSV_MCP_LOG_LEVEL. See docs/Logging.md.

AI / LLM

Does qsv send my data to OpenAI?

Only if you tell it to. qsv describegpt calls whichever LLM endpoint you point it at via QSV_LLM_BASE_URL — that can be OpenAI, but it can equally be Ollama on localhost, LM Studio, Jan, or any OpenAI-compatible endpoint.

The qsv MCP Server and Claude Cowork Plugin only send statistical summaries (stats + frequency) as LLM context, not the raw rows. See Discussions: Why MCP?.

Is describegpt deterministic?

The statistical context is deterministic (qsv's stats and frequency caches). The LLM narrative is not (LLMs are stochastic). In SQL-RAG sub-mode, the LLM writes SQL that qsv runs — the SQL output IS deterministic.

Reporting bugs

Where do I report bugs?

• Questions: Discussions Q&A
• FAQ-worthy: Discussions FAQ
• Confirmed bugs: Issues
• Security: SECURITY.md

Include qsv --version, qsv --envlist, and a minimal reproducer.

Can I contribute?

Yes — the project welcomes PRs. See CONTRIBUTING.md for the development setup. qsv uses AI tools heavily and credits the agent/model used in commit messages and PR descriptions; contributors must do the same (see the README's AI Policy and CONTRIBUTING.md). For wiki edits, see Contributing to the Wiki.

See also

• Troubleshooting — specific error → fix
• Comparison vs others
• Discussions → FAQ category — the evolving canonical Q&A
• Discussions → Q&A category
• External Resources
• Contributing to the Wiki