Skip to main content

VisiData Configuration Debugging

.visidatarc is a Python file executed at startup. Any syntax error silently prevents your config from loading. Plugin failures may crash the startup entirely. This page gives you a systematic diagnostic procedure.

Learning Focus

Always test .visidatarc with python3 ~/.visidatarc before opening VisiData. If it errors, fix the error. If it passes, the problem is a VisiData-specific API issue.

Step 1 — Test Syntax with Python​

python3 ~/.visidatarc

If this errors, it's a Python syntax problem — not a VisiData problem:

File "/home/user/.visidatarc", line 14
  options.undo = True
IndentationError: unexpected indent

Fix the indentation, then test again.

Step 2 — Identify Which Line Fails​

Add print statements to narrow down the failing line:

# ~/.visidatarc
print("line 1: loading options")
options.undo = True

print("line 2: loading colors")
color_current_row = 'bold white on 27'

print("line 3: loading plugins")
import visidata_plugin_name   # ← if this crashes, you see it here

Run python3 ~/.visidatarc and watch where output stops.

Step 3 — Start VisiData with No Config​

vd --config /dev/null somefile.csv

If VisiData works fine with no config, your .visidatarc has an error. Bisect to find it.

Step 4 — Check VisiData Options API​

The most common error is using the wrong API. VisiData v3+ uses:

# CORRECT (v3)
options.undo = True

# WRONG — this was an older style
vd.options.undo = True

Or for color_* options:

# CORRECT
options.color_current_row = 'bold white on 27'

# Also valid as module-level assignment
color_current_row = 'bold white on 27'

Common Configuration Errors​

Option Not Persisting​

Symptom: You changed an option in the Options Sheet (Shift+O), but it resets after restarting VisiData.

Fix: Save from inside the Options Sheet:

Shift+O
# Navigate to option
# Press e → edit value
# Press Ctrl+S → saves to ~/.visidatarc

Custom Key Conflicts​

Symptom: A key you bound in .visidatarc doesn't work, or overrides something unexpectedly.

Diagnosis:

# Inside VisiData:
z Ctrl+H
# Shows all commands for current sheet type with their bound keys

Fix in .visidatarc:

# Bind F5 to frequency table (safe — F-keys rarely conflict)
bindkey('KEY_F(5)', 'freq-col')

# If a key is already bound and you need to rebind:
bindkey('^R', 'reload-sheet')   # overrides default Ctrl+R

Plugin Import Error​

Symptom: VisiData crashes on startup with ImportError or ModuleNotFoundError.

Fix:

# Check which plugin is failing
python3 ~/.visidatarc

# Install the missing module
pip install missing-module-name

# Or comment out the plugin temporarily
# import failing_plugin   ← add # to comment out

Aggregator Not Appearing​

Symptom: You defined a custom aggregator but it doesn't appear in the + prompt.

Common mistake:

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

# CORRECT — must register with vd.aggregator()
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')

Minimal Working .visidatarc​

If your config is broken and you need to rebuild it safely:

# ~/.visidatarc — minimal safe starter

# Enable undo (most important)
options.undo = True

# Quit guard (prevents accidental exit with unsaved changes)
options.quitguard = True

# Date display format
options.disp_date_fmt = '%Y-%m-%d'

# Null display
options.disp_note_none = '⌀'

Test this works:

python3 ~/.visidatarc   # should print nothing and exit cleanly
vd --version            # should start and show version

Then add your customizations one block at a time, testing after each.

Environment Variable Issues​

# If VisiData isn't loading your config:
echo $HOME              # confirm home directory
ls -la ~/.visidatarc    # confirm file exists and has content

# Check VisiData's config path
vd --help | grep config

Troubleshooting Reference​

SymptomCauseFix
VisiData starts but config isn't appliedSyntax error in .visidatarcpython3 ~/.visidatarc → fix error
NameError: name 'vd' is not definedUsing vd.aggregator() before vd is availableRemove vd. prefix — use vd.aggregator() inside a function or use module-level aggregator()
Colors not applyingWrong option name (e.g., color_cursor_row vs color_current_row)Check z Ctrl+H inside VisiData for valid option names
Plugin crashes startupIncompatible plugin versionComment it out; check plugin's VisiData version requirement
Key binding does nothingKey name wrongUse KEY_F(5) not F5; check with z Ctrl+H

What's Next​