Configuring VisiData

VisiData’s behavior can be configured several ways:

  • vd command-line arguments
  • The global options sheet
  • Sheet-specific options sheets
  • The ~/.visidatarc file

vd command-line arguments

When you launch vd, you can specify certain behaviors via arguments on the command-line.

For instance, to tell VisiData to ignore the first three lines of your input file, you’d run the following:

vd my-spreadsheet.csv --skip 3

To see the full list of configurable options, run vd -h:

vd(1)                        Quick Reference Guide                       vd(1)                      
NAME                     
     VisiData -- a terminal utility for exploring and arranging tabular data                        
SYNOPSIS                 
     vd [options] [input ...]                     
     vd [options] --play cmdlog [-w waitsecs] [--batch] [-o output] [field=value]                   
     vd [options] [input ...] +toplevel:subsheet:col:row                                            
DESCRIPTION              
     VisiData is an easy-to-use multipurpose tool to explore, clean, edit, and restructure          
     data. Rows can be selected, filtered, and grouped; columns can be rearranged, trans-           
     formed, and derived via regex or Python expressions; and workflows can be saved, doc-          
     umented, and replayed.                       
   REPLAY MODE           
     -p, --play=cmdlog       replay a saved cmdlog within the interface                             
     -w, --replay-wait=seconds                    
                             wait seconds between commands                                          
     -b, --batch             replay in batch mode (with no interface)                               
     -o, --output=file       save final visible sheet to file as .tsv                               
:                        

(Press Space to scroll down the list.)

The global options sheet

You can also set most of the same options, plus additional color/display options, through the “global options sheet”. To launch that sheet, press Shift-O. You should see something like this:

  File  Edit  View  Column  Row  Data  Plot  System  Help     Ctrl+H for help menu                  
 option              global_value       | default            | description                       > 
 visidata_dir       ║ ~/.visidata/       | ~/.visidata/       | directory to load and store additi… 
 disp_splitwin_pct                      | 0                 #| height of second sheet on screen    
 mouse_interval                         | 1                 #| max time between press/release for… 
 null_value                             |                   | a value to be counted as null       
 undo                                   | True               | enable undo/redo                    
 disp_currency_fmt                      | %.02f              | default fmtstr to format for curre… 
 disp_float_fmt                         | {:.02f}            | default fmtstr to format for float… 
 disp_int_fmt                           | {:.0f}             | default fmtstr to format for int v… 
 disp_date_fmt                          | %Y-%m-%d           | default fmtstr to strftime for dat… 
 col_cache_size                         | 0                 #| max number of cache entries in eac… 
 clean_names                            | False              | clean column/sheet names to be val… 
 default_width                          | 20                #| default column width                
 default_height                         | 4                 #| default column height               
 textwrap_cells                         | True               | wordwrap text for multiline rows    
 quitguard                              | False              | confirm before quitting modified s… 
 debug                                  | False              | exit on error and display stacktra… 
 skip                                   | 0                 #| skip N rows before header           
 header                                 | 1                 #| parse first N rows as column names  
 load_lazy                              | False              | load subsheets always (False) or l… 
 force_256_colors                       | False              | use 256 colors even if curses repo… 
 disp_note_none                         |                  | visible contents of a cell whose v… 
Shift+O› global_options|                                 Shift+O   quit-sheet       168 options  •0 

To customize an option navigate to the global_value cell in the option’s row, and press e to edit it, like you would with any other cell in VisiData.

For example, to change VisiData’s default column width from 20 to 10, navigate down to the default_width row, over to the global_value cell, press e, type 10, and then press Enter. Once you do, the global options sheet should look like this:

  File  Edit  View  Column  Row  Data  Plot  System  Help     Ctrl+H for help menu                  
 option              global_value       | default            | description                       > 
 visidata_dir        ~/.visidata/       | ~/.visidata/       | directory to load and store additi… 
 disp_splitwin_pct                      | 0                 #| height of second sheet on screen    
 mouse_interval                         | 1                 #| max time between press/release for… 
 null_value                             |                   | a value to be counted as null       
 undo                                   | True               | enable undo/redo                    
 disp_currency_fmt                      | %.02f              | default fmtstr to format for curre… 
 disp_float_fmt                         | {:.02f}            | default fmtstr to format for float… 
 disp_int_fmt                           | {:.0f}             | default fmtstr to format for int v… 
 disp_date_fmt                          | %Y-%m-%d           | default fmtstr to strftime for dat… 
 col_cache_size                         | 0                 #| max number of cache entries in eac… 
 clean_names                            | False              | clean column/sheet names to be val… 
 default_width      ║ 10                #| 20                #| default column width                
 default_height                         | 4                 #| default column height               
 textwrap_cells                         | True               | wordwrap text for multiline rows    
 quitguard                              | False              | confirm before quitting modified s… 
 debug                                  | False              | exit on error and display stacktra… 
 skip                                   | 0                 #| skip N rows before header           
 header                                 | 1                 #| parse first N rows as column names  
 load_lazy                              | False              | load subsheets always (False) or l… 
 force_256_colors                       | False              | use 256 colors even if curses repo… 
 disp_note_none                         |                  | visible contents of a cell whose v… 
Shift+O› global_options| "10"                                 e   edit-option       168 options  •0 

As with any other sheet, you can leave the global options sheet, and return to your previous sheet, by pressing q.

Sheet-specific options sheets

As the name suggests, the changes you make on the global options sheet affect your entire VisiData session. To change VisiData’s behavior for just one sheet, type zO to edit the “sheet options sheet”:

  File  Edit  View  Column  Row  Data  Plot  System  Help     Ctrl+H for help menu                  
 option              sheet_value        | default            | description                       > 
 visidata_dir       ║                    | ~/.visidata/       | directory to load and store additi… 
 disp_splitwin_pct                      | 0                 #| height of second sheet on screen    
 mouse_interval                         | 1                 #| max time between press/release for… 
 null_value                             |                   | a value to be counted as null       
 undo                                   | True               | enable undo/redo                    
 disp_currency_fmt                      | %.02f              | default fmtstr to format for curre… 
 disp_float_fmt                         | {:.02f}            | default fmtstr to format for float… 
 disp_int_fmt                           | {:.0f}             | default fmtstr to format for int v… 
 disp_date_fmt                          | %Y-%m-%d           | default fmtstr to strftime for dat… 
 col_cache_size                         | 0                 #| max number of cache entries in eac… 
 clean_names                            | False              | clean column/sheet names to be val… 
 default_width                          | 20                #| default column width                
 default_height                         | 4                 #| default column height               
 textwrap_cells                         | True               | wordwrap text for multiline rows    
 quitguard                              | False              | confirm before quitting modified s… 
 debug                                  | False              | exit on error and display stacktra… 
 skip                                   | 0                 #| skip N rows before header           
 header                                 | 1                 #| parse first N rows as column names  
 load_lazy                              | False              | load subsheets always (False) or l… 
 force_256_colors                       | False              | use 256 colors even if curses repo… 
 disp_note_none                         |                  | visible contents of a cell whose v… 
e› faa-wildlife-strikes_options|                        zShift+O   quit-sheet       168 options  •0 

It the sheet options sheet operates just like the global options sheet, but applies only to the sheet you were on when you typed zO.

The ~/.visidatarc file

The approaches above all affect only your current VisiData session. When you quit VisiData, those customizations evaporate.

To persist your customizations from session to session, you can specify them in your computer’s ~/.visidatarc file.

Open that file in the editor of your choosing and, for each option you wish to modify, write options.my_example_option = my_custom_value.

For instance:

options.default_width = 10
options.encoding = "latin-1"
options.bulk_select_clear = True

… and then save the file. Next time you run VisiData, these options will take effect.

Note

The ~/.visidatarc file expects its commands to be written in Python. For basic options-setting, it doesn’t matter too much whether you know Python, as long as you follow the pattern in the example above. Numbers can be written plainly, strings of characters should be wrapped in quotation marks, and True/False values need to be written exactly as such.

Tip

If you know Python and are willing to acquaint yourself with VisiData’s architecture, you can use your ~/.visidatarc file to customize VisiData in ways far more powerful than simple option-setting — including creating your own commands.