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 | less:

usage: vd [-h] [-f FILETYPE] [-y] [-p PLAY] [-b] [-o OUTPUT] [-w REPLAY_WAIT]                       
          [-d DELIMITER] [--diff DIFF] [-v] [--encoding ENCODING]                                   
          [--encoding-errors ENCODING_ERRORS] [--regex-flags REGEX_FLAGS]                           
          [--default-width DEFAULT_WIDTH] [--wrap] [--bulk-select-clear]                            
          [--cmd-after-edit CMD_AFTER_EDIT] [--col-cache-size COL_CACHE_SIZE]                       
          [--quitguard] [--null-value NULL_VALUE] [--force-valid-colnames]                          
          [--debug] [--curses-timeout CURSES_TIMEOUT] [--force-256-colors]                          
          [--use-default-colors] [--note-pending NOTE_PENDING]                                      
          [--note-format-exc NOTE_FORMAT_EXC]     
          [--note-getter-exc NOTE_GETTER_EXC] [--note-type-exc NOTE_TYPE_EXC]                       
          [--note-unknown-type NOTE_UNKNOWN_TYPE] [--scroll-incr SCROLL_INCR]                       
          [--skip SKIP] [--confirm-overwrite CONFIRM_OVERWRITE]                                     
          [--safe-error SAFE_ERROR] [--header HEADER] [--delimiter DELIMITER]                       
          [--filetype FILETYPE] [--save-filetype SAVE_FILETYPE]                                     
          [--tsv-safe-newline TSV_SAFE_NEWLINE] [--tsv-safe-tab TSV_SAFE_TAB]                       
          [--clipboard-copy-cmd CLIPBOARD_COPY_CMD] [--visibility VISIBILITY]                       
          [--min-memory-mb MIN_MEMORY_MB] [--replay-wait REPLAY_WAIT]                               
          [--replay-movement] [--visidata-dir VISIDATA_DIR]                                         
          [--rowkey-prefix ROWKEY_PREFIX] [--cmdlog-histfile CMDLOG_HISTFILE]                       
          [--regex-maxsplit REGEX_MAXSPLIT]       
          [--show-graph-labels SHOW_GRAPH_LABELS] [--plot-colors PLOT_COLORS]                       
          [--zoom-incr ZOOM_INCR] [--motd-url MOTD_URL] [--profile PROFILE]                         
          [--csv-dialect CSV_DIALECT] [--csv-delimiter CSV_DELIMITER]                               
:

(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:

 option              global_value   | default           | description        | replayable         
 encoding           ‖                | utf-8             | encoding passed to…| True         ‖      
 encoding_errors            | surrogateescape   | encoding_errors pa…| True         ‖      
 regex_flags                        | I                 | flags to pass to r…| True         ‖      
 default_width            | 20               #| default column wid…| True         ‖      
 wrap               ‖                | False             | wrap text to fit w…| False        ‖      
 bulk_select_clear            | False             | clear selected row…| True         ‖      
 cmd_after_edit           | go-down           | command longname t…| False        ‖      
 col_cache_size               | 0                #| max number of cach…| False        ‖      
 quitguard                    | False             | confirm before qui…| False        ‖      
 null_value                 |                  | a value to be coun…| True         ‖      
 force_valid_colnam…          | False             | clean column names…| True         ‖      
 debug                        | False             | exit on error and …| False        ‖      
 curses_timeout               | 100              #| curses timeout in …| False        ‖      
 force_256_colors   ‖                | False             | use 256 colors eve…| False        ‖      
 use_default_colors          | False             | curses use default…| False        ‖      
 disp_note_none     ‖                | ⌀                 | visible contents o…| False        ‖      
 disp_truncator               | …                 | indicator that the…| False        ‖      
 disp_oddspace                | ·                 | displayable charac…| False        ‖      
 disp_unprintable             | .                 | substitute charact…| False        ‖      
 disp_column_sep              | |                 | separator between …| False        ‖      
 disp_keycol_sep              | ‖                 | separator between …| False        ‖      
 disp_status_fmt            | {sheet.name}|     | status line prefix | False        ‖      
global_options|                                                                O       100 options  

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:

 option              global_value   | default           | description        | replayable         
 encoding                           | utf-8             | encoding passed to…| True         ‖      
 encoding_errors                    | surrogateescape   | encoding_errors pa…| True         ‖      
 regex_flags                        | I                 | flags to pass to r…| True         ‖      
 default_width       10            #| 20               #| default column wid…| True         ‖      
 wrap                               | False             | wrap text to fit w…| False        ‖      
 bulk_select_clear                  | False             | clear selected row…| True         ‖      
 cmd_after_edit                     | go-down           | command longname t…| False        ‖      
 col_cache_size                     | 0                #| max number of cach…| False        ‖      
 quitguard                          | False             | confirm before qui…| False        ‖      
 null_value                         |                  | a value to be coun…| True         ‖      
 force_valid_colnam…                | False             | clean column names…| True         ‖      
 debug                              | False             | exit on error and …| False        ‖      
 curses_timeout                     | 100              #| curses timeout in …| False        ‖      
 force_256_colors                   | False             | use 256 colors eve…| False        ‖      
 use_default_colors                 | False             | curses use default…| False        ‖      
 disp_note_none                     | ⌀                 | visible contents o…| False        ‖      
 disp_truncator                     | …                 | indicator that the…| False        ‖      
 disp_oddspace                      | ·                 | displayable charac…| False        ‖      
 disp_unprintable                   | .                 | substitute charact…| False        ‖      
 disp_column_sep                    | |                 | separator between …| False        ‖      
 disp_keycol_sep                    | ‖                 | separator between …| False        ‖      
 disp_status_fmt                    | {sheet.name}|     | status line prefix | False        ‖      
global_options| "10"                                                           e       100 options  

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”:

 option              sheet_value   | default           | description        | replayable          
 encoding           ‖               | utf-8             | encoding passed to…| True         ‖       
 encoding_errors    ‖               | surrogateescape   | encoding_errors pa…| True         ‖       
 regex_flags                       | I                 | flags to pass to r…| True         ‖       
 default_width                     | 20               #| default column wid…| False        ‖       
 wrap                              | False             | wrap text to fit w…| False        ‖       
 bulk_select_clear  ‖               | False             | clear selected row…| True         ‖       
 cmd_after_edit                    | go-down           | command longname t…| False        ‖       
 col_cache_size     ‖               | 0                #| max number of cach…| False        ‖       
 quitguard          ‖               | False             | confirm before qui…| False        ‖       
 null_value         ‖               |                  | a value to be coun…| True         ‖       
 force_valid_colnam…‖               | False             | clean column names…| True         ‖       
 debug              ‖               | False             | exit on error and …| False        ‖       
 curses_timeout     ‖               | 100              #| curses timeout in …| False        ‖       
 force_256_colors                  | False             | use 256 colors eve…| False        ‖       
 use_default_colors ‖               | False             | curses use default…| False        ‖       
 disp_note_none                    | ⌀                 | visible contents o…| False        ‖       
 disp_truncator     ‖               | …                 | indicator that the…| False        ‖       
 disp_oddspace      ‖               | ·                 | displayable charac…| False        ‖       
 disp_unprintable   ‖               | .                 | substitute charact…| False        ‖       
 disp_column_sep    ‖               | |                 | separator between …| False        ‖       
 disp_keycol_sep    ‖               | ‖                 | separator between …| False        ‖       
 disp_status_fmt    ‖               | {sheet.name}|     | status line prefix | False        ‖       
faa-wildlife-strikes_options|                                                 zO       100 options  

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.

Note

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.