Environment Variables

Environment Variables

Tier: Advanced

Canonical reference: docs/ENVIRONMENT_VARIABLES.md. 50+ variables total — this page groups them by purpose and links the canonical reference for definitions.

Run qsv --envlist to see all active qsv-relevant env vars in your environment.

qsv also supports .env files. See docs/ENVIRONMENT_VARIABLES.md#env-file-support for the lookup order.

Quick reference — the most-used vars

Variable	What it does
QSV_AUTOINDEX_SIZE	Auto-create .idx for files > N bytes (and auto-refresh stale ones)
QSV_STATSCACHE_MODE	auto (default), force (auto-create cache), or none
QSV_MAX_JOBS	Cap the number of parallel jobs
QSV_TMPDIR	Spill directory for extsort / extdedup
QSV_LLM_BASE_URL, QSV_LLM_APIKEY, QSV_LLM_MODEL	describegpt LLM config
QSV_DEFAULT_DELIMITER	Override the input delimiter
QSV_SNIFF_DELIMITER	Auto-detect the input delimiter
QSV_LOG_LEVEL, QSV_LOG_DIR	Logging

I/O & format

• QSV_DEFAULT_DELIMITER — override input delimiter (default , for CSV, \t for TSV)
• QSV_SNIFF_DELIMITER — auto-detect delimiter; overrides the above
• QSV_SNIFF_PREAMBLE — auto-detect preamble line count
• QSV_NO_HEADERS — treat the first row as data, not headers
• QSV_TOGGLE_HEADERS — invert header behavior
• QSV_COMMENT_CHAR — skip lines starting with this character
• QSV_OUTPUT_BOM — add a UTF-8 BOM to outputs (Excel-friendly on Windows)
• QSV_RDR_BUFFER_CAPACITY — reader buffer size (default 128 KB)
• QSV_WTR_BUFFER_CAPACITY — writer buffer size (default 512 KB)
• QSV_SKIP_FORMAT_CHECK — skip MIME-type inference for inputs

Performance & memory

• QSV_AUTOINDEX_SIZE — auto-create / refresh index for files > N bytes
• QSV_MAX_JOBS — max parallel jobs (default: all logical CPUs)
• QSV_MEMORY_CHECK — enable pre-check that the file fits before running memory-mode commands
• QSV_FREEMEMORY_HEADROOM_PCT — reserve N% of free RAM (default 20)
• QSV_STATS_CHUNK_MEMORY_MB — per-chunk memory limit in stats
• QSV_FREQ_CHUNK_MEMORY_MB — per-chunk memory limit in frequency
• QSV_FREQ_HIGH_CARD_THRESHOLD — absolute cardinality threshold for HIGH_CARDINALITY classification
• QSV_FREQ_HIGH_CARD_PCT — percentage-of-rowcount cardinality threshold

See Performance Tuning for how these interact.

Cache config

• QSV_STATSCACHE_MODE — auto / force / none
• QSV_CACHE_DIR — directory for lookup-table downloads (Luau qsv_register_lookup)
• QSV_DISKCACHE_TTL_SECS — fetch / fetchpost / describegpt disk-cache TTL (default 28 days)
• QSV_DISKCACHE_TTL_REFRESH — extend TTL on cache hit
• QSV_REDIS_CONNSTR — Redis connection string for fetch cache (default redis://127.0.0.1:6379/1)
• QSV_FP_REDIS_CONNSTR — Redis connection for fetchpost cache (default db 2)
• QSV_DG_REDIS_CONNSTR — Redis connection for describegpt cache (default db 3)
• QSV_REDIS_MAX_POOL_SIZE — Redis connection pool size
• QSV_REDIS_TTL_SECS — Redis cache TTL
• QSV_REDIS_TTL_REFRESH — extend Redis TTL on cache hit

See Stats Cache & Caching and HTTP & Web.

AI & LLM

• QSV_LLM_BASE_URL — OpenAI-compatible LLM endpoint for describegpt
• QSV_LLM_APIKEY — API key for the LLM
• QSV_LLM_MODEL — model name (e.g. openai/gpt-oss-20b, google/gemma-4-31b)
• QSV_DUCKDB_PATH — DuckDB binary path (enables DuckDB SQL in describegpt & scoresql)
• QSV_TEST_DESCRIBEGPT — enable describegpt tests (requires LM Studio with openai/gpt-oss-20b)

See AI & Documentation.

Web & HTTP

• QSV_TIMEOUT — timeout in seconds for fetch, fetchpost, geocode, sniff, validate, describegpt, template, sample, snappy, luau (default 30)
• QSV_USER_AGENT — custom User-Agent header (supports $QSV_VERSION, $QSV_TARGET, $QSV_BIN_NAME, $QSV_COMMAND placeholders)
• QSV_CKAN_API — CKAN action API endpoint for ckan:// URL scheme
• QSV_CKAN_TOKEN — CKAN access token (only required for private resources)
• Plus standard HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY

Geocoding

• QSV_GEOIP2_FILENAME — MaxMind GeoLite2 binary database filename (default GeoLite2-City.mmdb)
• QSV_GEOCODE_INDEX_FILENAME — custom Geonames index file

See Geospatial.

Stats output config

• QSV_STATS_STRING_MAX_LENGTH — truncate long min/max string values
• QSV_STATS_SEPARATOR — separator for multi-value MODE/ANTIMODE/PERCENTILE cells (default |)
• QSV_ANTIMODES_LEN — max characters when listing antimodes (default 100)

Date parsing

• QSV_PREFER_DMY — parse dates as DMY instead of MDY (affects datefmt, frequency, joinp, moarstats, pivotp, sample, schema, sniff, stats, tojsonl)

Regex

• QSV_REGEX_UNICODE — make search / searchset / replace unicode-aware (slower; default off)

Color / display

• QSV_FORCE_COLOR — force color output even in CI / pipes
• QSV_THEME — DARK or LIGHT (overrides terminal-bg detection)
• QSV_TERMWIDTH — override detected terminal width

See AI & Documentation → color.

Logging

• QSV_LOG_LEVEL — error / warn / info / trace / debug (default off; qsvmcp defaults to info)
• QSV_LOG_DIR — log file directory (auto-created if missing)
• QSV_LOG_UNBUFFERED — write log lines synchronously
• QSV_PROGRESSBAR — enable --progressbar on commands that support it
• QSV_NO_UPDATE — disable qsv --update self-update version check

See docs/Logging.md.

Polars-specific

Polars commands respect Polars's own env vars:

• POLARS_VERBOSE — verbose logging to stderr
• POLARS_PANIC_ON_ERR — panic on Polars errors
• POLARS_BACKTRACE_IN_ERR — include backtrace in Polars errors
• QSV_POLARS_FLOAT_PRECISION — float precision for Polars → CSV conversion
• QSV_POLARS_DECIMAL_SCALE — Polars Decimal scale (default 5)

MCP server (qsvmcp only)

The MCP server has its own dedicated environment variable namespace — see MCP Server and the canonical reference's MCP section.

Key ones:

• QSV_MCP_BIN_PATH — full path to qsv/qsvmcp binary
• QSV_MCP_WORKING_DIR — default working directory (supports ${HOME}, ${DOWNLOADS}, ${DOCUMENTS}, …)
• QSV_MCP_ALLOWED_DIRS — additional accessible directories (colon-separated on Unix)
• QSV_MCP_OPERATION_TIMEOUT_MS — operation timeout (default 600,000 = 10 min)
• QSV_MCP_MAX_OUTPUT_SIZE — max bytes before output is saved to disk (default 50 MB)
• QSV_MCP_MAX_CONCURRENT_OPERATIONS — concurrency cap (default 3 in plugin mode, 1 in extension mode)
• QSV_MCP_LOG_LEVEL — info / error / off (separate from QSV_LOG_LEVEL)
• QSV_MCP_USE_DUCKDB — enable DuckDB SQL when available
• QSV_MCP_OUTPUT_FORMAT — tsv (default) or csv

Dotenv (.env) files

qsv loads .env files in this order:

1. The file at QSV_DOTENV_PATH if set (overrides everything; set to <NONE> to disable)
2. .env in the current working directory
3. <binary-name>.env next to the qsv binary itself (e.g. /usr/local/bin/qsv.env)

Set QSV_DOTENV_PATH=<NONE> to disable dotenv processing entirely.

Dependencies

Some env vars come from qsv's dependencies, not qsv itself:

• mimalloc — see microsoft/mimalloc env options
• jemalloc — see jemalloc env options
• reqwest proxies — HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY

Discover at runtime

qsv --envlist
# Lists every QSV_* variable currently set in your environment,
# plus allocator-specific (MIMALLOC_*/JEMALLOC_*) and proxy vars.

See also

• docs/ENVIRONMENT_VARIABLES.md — canonical reference (source of truth)
• Performance Tuning — when to set each performance var
• Stats Cache & Caching
• HTTP & Web
• AI & Documentation
• Geospatial
• MCP Server — MCP-specific env vars
• docs/Logging.md