Options Reference
VisiData options control display, behavior, performance, and editing. All options can be set in .visidatarc, passed on the command line with --option value, or changed at runtime with Shift+O.
Learning Focus
Use this as a quick-lookup reference when tuning VisiData behavior. Options in .visidatarc use options.name = value syntax. Command-line equivalents use --name value.
Tool Snapshot
- Runtime options sheet:
Shift+O - Config file:
~/.visidatarc - CLI override:
vd --option-name value file.csv - Inspect current value: open
Shift+O, search with/
Display Options
| Option | Default | Type | Description |
|---|---|---|---|
disp_date_fmt | %Y-%m-%d | str | Display format for date columns (@ type) |
disp_float_fmt | {:.02f} | str | Display format for float columns (% type) |
disp_currency_fmt | {:,.02f} | str | Display format for currency columns ($ type) |
disp_int_fmt | {} | str | Display format for integer columns (# type) |
disp_null_value | `` | str | String shown for None/null values |
disp_truncator | … | str | Character appended when cell value is truncated |
disp_note_none | ⌀ | str | Character shown in status for null cells |
color_default | normal | str | Default text color |
color_selected_row | 215 bold | str | Color for selected rows (yellow by default) |
color_key_col | 81 bold | str | Color for key columns (blue) |
color_error | red | str | Color for error cells (#ERR) |
color_warning | yellow | str | Color for warning indicators |
color_column_sep | 246 blue | str | Column separator line color |
disp_column_sep | | | str | Character between columns |
disp_rowlen | 0 | int | Max row display length (0 = unlimited) |
# .visidatarc examples
options.disp_date_fmt = '%d/%m/%Y' # UK date format
options.disp_null_value = 'N/A' # Show N/A for nulls
options.color_selected_row = 'green bold'
Loading & Parsing Options
| Option | Default | Type | Description |
|---|---|---|---|
filetype | `` | str | Default filetype when extension unrecognized |
encoding | utf-8 | str | File encoding (try latin1 for legacy files) |
delimiter | , | str | CSV field delimiter |
quotechar | " | str | CSV quote character |
skip | 0 | int | Number of header lines to skip on load |
header | 1 | int | Number of rows to use as column headers |
max_rows | 0 | int | Max rows to load (0 = all rows) |
csv_dialect | excel | str | CSV dialect (excel, unix, excel-tab) |
tsv_safe_newline | \u2028 | str | Replacement for newlines inside TSV cells |
json_indent | None | int | JSON pretty-print indent (None = compact) |
safe_error | #ERR | str | Value displayed when expression throws an error |
# .visidatarc examples
options.encoding = 'latin1' # For legacy Windows exports
options.delimiter = ';' # Semicolon-delimited files
options.skip = 1 # Skip one comment header line
options.max_rows = 50000 # Load max 50k rows
Editing Options
| Option | Default | Type | Description |
|---|---|---|---|
undo | False | bool | Enable undo/redo (U/R) — set to True in .visidatarc |
quitguard | False | bool | Prompt before quitting unsaved modified sheets |
overwrite | False | bool | Overwrite source file on Ctrl+S without prompting |
confirm_overwrite | True | bool | Confirm before overwriting existing files |
# .visidatarc recommended settings
options.undo = True
options.quitguard = True
Performance Options
| Option | Default | Type | Description |
|---|---|---|---|
max_rows | 0 | int | Limit rows loaded (0 = no limit) |
min_memory_mb | 0 | int | Warn when free memory drops below this MB value |
bulk_select_rows | 1000 | int | Rows processed per cycle during bulk selection |
regex_maxsplit | 0 | int | Max splits for regex column split (0 = unlimited) |
Navigation Options
| Option | Default | Type | Description |
|---|---|---|---|
wrap | False | bool | Wrap long cell values to multiple display lines |
scroll_incr | 3 | int | Number of rows scrolled per scroll command |
name_joiner | _ | str | Character joining split column names |
aggr_roundtrip | False | bool | Round-trip aggregated columns back to source type |
Output & Saving Options
| Option | Default | Type | Description |
|---|---|---|---|
save_filetype | `` | str | Default save format if output filename has no extension |
tsv_safe_tab | \u00b7 | str | Replacement for literal tabs in TSV output |
csv_lineterminator | \r\n | str | Line ending for CSV output |
json_sort_keys | False | bool | Sort keys alphabetically in JSON output |
CommandLog & Replay Options
| Option | Default | Type | Description |
|---|---|---|---|
replay_wait | 0 | float | Seconds to pause between replayed commands |
replay_movement | False | bool | Include cursor-movement commands in CommandLog |
rowkey_prefix | `` | str | Prefix for row key columns in CommandLog |
# For slow, visible replays (useful for demos)
options.replay_wait = 0.5
Practical Reference — Most-Used in .visidatarc
# ~/.visidatarc — recommended baseline
# Core editing safety
options.undo = True
options.quitguard = True
# Date format for UK/EU locales
options.disp_date_fmt = '%d/%m/%Y'
# Show blanks explicitly
options.disp_null_value = '∅'
# Performance guard for large files
options.max_rows = 100000
# Slow replay for demos
# options.replay_wait = 0.3
Runtime: Changing Options in Shift+O
Open the Options Sheet at runtime:
Shift+O open global Options Sheet
zO open options for current sheet only
Inside the Options Sheet:
- Navigate with arrow keys
- Press
eon any row to edit the value - Changes apply immediately — no restart needed
- Press
Ctrl+Sto persist changes to.visidatarc
Hands-On Practice
vd ~/github/practice-folder/visidata/01-loading/01-employees.csv
# 1. Press Shift+O to open the Options Sheet
# 2. Search: / → type: disp_null_value → Enter
# 3. Press e → change value to 'N/A' → Enter
# 4. Press q → return to sheet
# 5. Verify nulls now display as 'N/A'
# 6. In status bar, note the option applied live