Skip to main content

VisiData Configuration Basics

VisiData loads ~/.visidatarc at startup as a Python file. Any valid Python code can appear here — from simple options.key = value settings to custom aggregator definitions and key bindings.

Learning Focus

Start with the Options Sheet (Shift+O) to discover options visually, then migrate the ones you use most into ~/.visidatarc for persistence.

Options Sheet (Shift+O)​

Shift+O        # open Options Sheet (global — all sheets)
zO             # open Options Sheet (sheet-specific — current sheet only)
gO             # open ~/.visidatarc as a text sheet

Inside the Options Sheet:

Enter           edit option at current row
d               remove override for this context
^S              save changes to ~/.visidatarc

The Options Sheet shows every configurable option with its current value, default, and description.

Setting Options in .visidatarc​

Create or edit ~/.visidatarc:

# ~/.visidatarc

# Enable undo/redo (highly recommended)
options.undo = True

# Confirm before quitting a modified sheet
options.quitguard = True

# Default column width (0 = auto)
options.default_width = 20

# Number of rows to load per sheet (0 = all)
options.max_rows = 0

# Date format for @ (date) type columns
options.disp_date_fmt = '%Y-%m-%d'

# Default save format
options.save_filetype = 'csv'

# Skip N rows at the top of files (global default)
options.skip = 0

# Header row count
options.header = 1

# CSV delimiter default
options.csv_delimiter = ','

# Encoding default
options.encoding = 'utf-8-sig'

Custom Key Bindings​

# ~/.visidatarc

# Bind Ctrl+R to reload current sheet (like a browser)
bindkey('^R', 'reload-sheet')

# Bind F5 to open frequency table
bindkey('KEY_F(5)', 'freq-col')

# Bind Ctrl+G to go to a specific row number
bindkey('^G', 'go-row-number')

Find command longnames with z Ctrl+H inside VisiData (shows all commands for current sheet with longnames).

Custom Aggregators​

# ~/.visidatarc

def median(values):
    L = sorted(v for v in values if v is not None)
    if not L:
        return None
    return L[len(L) // 2]

vd.aggregator('median', median, 'median value')

After adding this, median is available as an aggregator in + prompts.

Display Options​

# ~/.visidatarc

# Show sidebar (context-sensitive help)
options.disp_sidebar = True

# Wrap long text in cells (multiline rows)
options.wrap = False

# Number of lines for multiline row display
options.disp_wrap_max_lines = 3

# Display null values as
options.disp_note_none = '⌀'

# Column separator character
options.disp_column_sep = '│'

Performance Options​

# ~/.visidatarc

# Cache column computations (0 = no cache)
options.col_cache_size = 0

# Minimum free memory in MB before pausing loading
options.min_memory_mb = 100

# Lazy loading of subsheets (True = load on demand)
options.load_lazy = False

Practical Configuration Example​

A recommended starter .visidatarc for server administrators:

# ~/.visidatarc — VisiData starter config for sysadmins

# Core behavior
options.undo = True
options.quitguard = True
options.save_filetype = 'csv'
options.encoding = 'utf-8-sig'

# Date handling
options.disp_date_fmt = '%Y-%m-%d %H:%M:%S'

# Memory safety
options.min_memory_mb = 100

# Display
options.disp_sidebar = True
options.wrap = False

# Custom aggregators
def median(values):
    L = sorted(v for v in values if v is not None)
    return L[len(L)//2] if L else None

vd.aggregator('median', median, 'median value')

# Custom key bindings
bindkey('KEY_F(5)', 'freq-col')     # F5 → frequency table
bindkey('KEY_F(6)', 'describe')     # F6 → describe sheet

Troubleshooting Matrix​

ProblemCauseFix
.visidatarc not loadedFile has syntax errorRun python3 ~/.visidatarc to check
Option not persistingSet via Options Sheet but not savedPress ^S inside Options Sheet
Custom key conflictsKey already bound to somethingCheck with z^H (command sheet)
Aggregator not appearingFunction not registeredVerify vd.aggregator(...) call syntax

Best Practices​

  • Enable options.undo = True before doing any data cleaning work.
  • Enable options.quitguard = True to prevent accidental exit without saving.
  • Use Shift+O to discover and test options interactively, then copy the ones that work into ~/.visidatarc.
  • Keep custom aggregators in a separate section at the bottom of .visidatarc for maintainability.

Hands-On Practice​

# Open your config file
nano ~/.visidatarc

# Add:
options.undo = True
options.quitguard = True

# Save and exit

# Verify in VisiData
vd /tmp/servers.csv
# Try: edit a cell (e), make a change, press U → should undo
# Try: gq → should prompt if sheet is modified

What's Next​