Explore
If you started an exploration session and can't get out: press "q" on your keyboard.
With the explore command you can open your dataset in Visidata which is an amazing visual tool for working with tabular data in Console. For example try "Shift+F" for creating data histograms!
Installation
pip install frictionless[visidata]
pip install frictionless[visidata,zenodo] # for examples in this tutorial
Example
For example, let's expore this interesing dataset:
frictionless explore https://zenodo.org/record/3977957
Documentation
Before entering Visidata, it's highly recommended to read its documentation:
You can get it in Console as well:
vd --help
vd(1) Quick Reference Guide vd(1)
NAME
VisiData — a terminal utility for exploring and arranging tabular data
SYNOPSIS
vd [options] [input ...]
visidata [options] [input ...]
vd [options] --play cmdlog [-w waitsecs] [--batch] [-i] [-o output]
[field=value]
vd [options] [input ...] +toplevel:subsheet:row:col
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, transformed, and derived via regex or Python expres‐
sions; and workflows can be saved, documented, 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)
-i, --interactive launch VisiData in interactive mode after batch
-o, --output=file save final visible sheet to file as .tsv
field=value replace "{field}" in cmdlog contents with value
Commands During Replay
^K cancel current replay
GLOBAL COMMANDS
All keystrokes are case sensitive. The ^ prefix is shorthand for Ctrl.
Keystrokes to start off with
^Q abort program immediately
^C cancel user input or abort all async threads on current
sheet
g^C abort all secondary threads
q quit current sheet or menu
Q quit current sheet and free associated memory
gq quit all sheets (clean exit)
Alt+H activate help menu (Enter/left-mouse to expand submenu
or execute command)
g^H view this man page
z^H view sheet of command longnames and keybindings for cur‐
rent sheet
gb open sidebar in a new sheet
b toggle sidebar
U undo the most recent modification (requires enabled
options.undo)
R redo the most recent undo (requires enabled
options.undo)
Space longname open command palette; execute top command by its
longname
Command Palette
Tab Move to command palette, and cycle through commands
0-9 Execute numbered command
Enter Execute highlighted command
Cursor Movement
Arrow PgUp go as expected
h j k l go left/down/up/right
gh gj gk gl go all the way to the left/bottom/top/right of sheet
G gg go all the way to the bottom/top of sheet
Ic. End Home go all the way to the bottom/top of sheet
^B ^F scroll one page back/forward
^Left ^Right scroll one page left/right
zz scroll current row to center of screen
^^ (Ctrl+^) jump to previous sheet (swaps with current sheet)
/ ? regex search for regex forward/backward in current column's
displayed values
g/ g? regex search for regex forward/backward over all visible
columns' displayed values
z/ z? expr search by Python expr forward/backward in current column
(with column names as variables)
n N go to next/previous match from last regex search
< > go up/down current column to next value
z< z> go up/down current column to next null value
{ } go up/down current column to next selected row
c regex go to next column with name matching regex
r regex go to next row with key matching regex
zc zr number go to column/row number (0-based)
H J K L slide current row/column left/down/up/right
gH gJ gK gL slide current row/column all the way to the left/bot‐
tom/top/right of sheet
zH zJ zK zK number
slide current row/column number positions to the
left/down/up/right
zh zj zk zl scroll one left/down/up/right
Column Manipulation
_ (underbar) toggle width of current column between full and default
width
g_ toggle widths of all visible columns between full and
default width
z_ number adjust width of current column to number
gz_ number adjust widths of all visible columns to Ar number
- (hyphen) hide current column
z- reduce width of current column by half
gv unhide all columns
! z! toggle/unset current column as a key column
~ # % $ @ z#
set type of current column to str/int/float/cur‐
rency/date/len
Alt++ Alt+- show more/less precision in current numerical column
^ rename current column
g^ rename all unnamed visible columns to contents of se‐
lected rows (or current row)
z^ rename current column to combined contents of current
cell in selected rows (or current row)
gz^ rename all visible columns to combined contents of cur‐
rent column for selected rows (or current row)
= expr create new column from Python expr, with column names,
and attributes, as variables
g= expr set current column for selected rows to result of Python
expr
gz= expr set current column for selected rows to the items in
result of Python sequence expr
z= expr evaluate Python expression on current row and set
current cell with result of Python expr
i add column with incremental values
gi set current column for selected rows to incremental
values
zi step add column with values at increment step
gzi step set current column for selected rows at increment step
' (tick) add a frozen copy of current column with all cells eval‐
uated
g' open a frozen copy of current sheet with all visible
columns evaluated
z' gz' add/reset cache for current/all visible column(s)
Note that regex operations apply to the displayed value in a cell.
: regex add new columns from regex split; number of columns
determined by example row at cursor
; regex add new columns from capture groups of regex (also
requires example row)
z; expr create new column from bash expr, with $columnNames as
variables
* regex/subst add column derived from current column, replacing regex
with subst (may include \1 backrefs)
g* gz* regex/subst
modify selected rows in current/all visible column(s),
replacing regex with subst (may include \1 backrefs)
( g( expand current/all visible column(s) of lists (e.g. [3])
or dicts (e.g. {3}) one level
z( gz( depth expand current/all visible column(s) of lists (e.g. [3])
or dicts (e.g. {3}) to given depth (0= fully)
) g( unexpand current/all visible column(s); restore original
column and remove other columns at this level
z) gz) depth contract current/all visible column(s) of former lists
(e.g. [3]) or dicts (e.g. {3}) to given depth (0= fully)
zM row-wise expand current column of lists (e.g. [3]) or
dicts (e.g. {3}) within that column
Row Selection
s t u select/toggle/unselect current row
gs gt gu select/toggle/unselect all rows
zs zt zu select/toggle/unselect all rows from top to cursor
gzs gzt gzu select/toggle/unselect all rows from cursor to bottom
| \ regex select/unselect rows matching regex in current column
g| g\ regex select/unselect rows matching regex in any visible
column
z| z\ expr select/unselect rows matching Python expr in any visible
column
, (comma) select rows matching display value of current cell in
current column
g, select rows matching display value of current row in all
visible columns
z, gz, select rows matching typed value of current cell/row in
current column/all visible columns
Row Sorting/Filtering
[ ] sort ascending/descending by current column; replace any
existing sort criteria
g[ g] sort ascending/descending by all key columns; replace
any existing sort criteria
z[ z] sort ascending/descending by current column; add to ex‐
isting sort criteria
gz[ gz] sort ascending/descending by all key columns; add to ex‐
isting sort criteria
" open duplicate sheet with only selected rows
g" open duplicate sheet with all rows
gz" open duplicate sheet with deepcopy of selected rows
The rows in these duplicated sheets (except deepcopy) are references to
rows on the original source sheets, and so edits to the filtered rows
will naturally be reflected in the original rows. Use g' to freeze sheet
contents in a deliberate copy.
Editing Rows and Cells
a za append blank row/column; appended columns cannot be
copied to clipboard
ga gza number append number blank rows/columns
d gd delete current/selected row(s)
y gy yank (copy) current/all selected row(s) to clipboard in
Memory Sheet
x gx cut (copy and delete) current/all selected row(s) to
clipboard in Memory Sheet
zy gzy yank (copy) contents of current column for
current/selected row(s) to clipboard in Memory Sheet
zd gzd set contents of current column for current/selected
row(s) to options.null_value
zx gzx cut (copy and delete) contents of current column for
current/selected row(s) to clipboard in Memory Sheet
p P paste clipboard rows after/before current row
zp gzp set cells of current column for current/selected row(s)
to last clipboard value
zP gzP paste to cells of current column for current/selected
row(s) using the system clipboard
Y gY yank (copy) current/all selected row(s) to system
clipboard (using options.clipboard_copy_cmd)
zY gzY yank (copy) contents of current column for
current/selected row(s) to system clipboard (using
options.clipboard_copy_cmd)
f fill null cells in current column with contents of non-
null cells up the current column
e text edit contents of current cell
ge text set contents of current column for selected rows to text
Commands While Editing Input
Enter ^C accept/abort input
^O g^O open external $EDITOR to edit contents of current/se‐
lected rows in current column
^R reload initial value
^A ^E go to beginning/end of line
^B ^F go back/forward one character
^← ^→ (arrow) go back/forward one word
^H ^D delete previous/current character
^T transpose previous and current characters
^U ^K clear from cursor to beginning/end of line
^Y paste from cell clipboard
Backspace Del delete previous/current character
Insert toggle insert mode
Up Down set contents to previous/next in history
Tab Shift+Tab move cursor left/right and re-enter edit mode
Shift+Arrow move cursor in direction of Arrow and re-enter edit
mode
Data Toolkit
o input open input in VisiData
zo open file or url from path in current cell
^S g^S filename save current/all sheet(s) to filename in format
determined by extension (default .tsv)
Note: if the format does not support multisave, or the
filename ends in a /, a directory will be created.
z^S filename save current column only to filename in format
determined by extension (default .tsv)
^D filename.vdj save CommandLog to filename.vdj file
A open new blank sheet with one column
T open new sheet that has rows and columns of current
sheet transposed
+ aggregator add aggregator to current column (see Frequency Table)
z+ aggregator display result of aggregator over values in selected
rows for current column; store result in Memory Sheet
& append top two sheets in Sheets Stack
g& append all sheets in Sheets Stack
w nBefore nAfter
add column where each row contains a list of that row,
nBefore rows, and nAfter rows
Data Visualization
. (dot) plot current numeric column vs key columns. The numeric
key column is used for the x-axis; categorical key column
values determine color.
g. plot a graph of all visible numeric columns vs key
columns.
If rows on the current sheet represent plottable coordinates (as in .shp
or vector .mbtiles sources), . plots the current row, and g. plots all
selected rows (or all rows if none selected).
Canvas-specific Commands
+ - increase/decrease zoom level, centered on cursor
_ (underbar) zoom to fit full extent
z_ (underbar) set aspect ratio
x xmin xmax set xmin/xmax on graph
y ymin ymax set ymin/ymax on graph
s t u select/toggle/unselect rows on source sheet con‐
tained within canvas cursor
gs gt gu select/toggle/unselect rows on source sheet visi‐
ble on screen
d delete rows on source sheet contained within can‐
vas cursor
gd delete rows on source sheet visible on screen
Enter open sheet of source rows contained within canvas
cursor
gEnter open sheet of source rows visible on screen
1 - 9 toggle display of layers
^L redraw all pixels on canvas
v toggle show_graph_labels option
mouse scrollwheel zoom in/out of canvas
left click-drag set canvas cursor
right click-drag scroll canvas
Split Screen
Z split screen in half, so that second sheet on the stack is
visible in a second pane
zZ split screen, and queries for height of second pane
Split Window specific Commands
gZ close an already split screen, current pane full
screens
Z push second sheet on current pane's stack to the
top of the other pane's stack
Tab jump to other pane
gTab swap panes
g Ctrl+^ cycle through sheets
Other Commands
Q quit current sheet and remove it from the CommandLog
v toggle sheet-specific visibility (multi-line rows on
Sheet, legends/axes on Graph)
^E g^E view traceback for most recent error(s)
z^E view traceback for error in current cell
^L refresh screen
^R reload current sheet
^Z suspend VisiData process
^G show cursor position and bounds of current sheet on sta‐
tus line
^V show version and copyright information on status line
^P open Status History
m keystroke first, begin recording macro; second, prompt for
keystroke , and complete recording. Macro can then be
executed everytime provided keystroke is used. Will
override existing keybinding. Macros will run on current
row, column, sheet.
gm open an index of all existing macros. Can be directly
viewed with Enter, and then modified with ^S.
^Y z^Y g^Y open current row/cell/sheet as Python object
^X expr evaluate Python expr and opens result as Python object
z^X expr evaluate Python expr, in context of current row, and
open result as Python object
g^X module import Python module in the global scope
Internal Sheets List
. Directory Sheet browse properties of files in a directory
. Guide Index read documentation from within VisiData
. Memory Sheet (Alt+Shift+M) browse saved values, including clipboard
Metasheets
. Columns Sheet (Shift+C) edit column properties
. Sheets Sheet (Shift+S) jump between sheets or join them together
. Options Sheet (Shift+O) edit configuration options
. Commandlog (Shift+D) modify and save commands for replay
. Error Sheet (Ctrl+E) view last error
. Status History (Ctrl+P) view history of status messages
. Threads Sheet (Ctrl+T) view, cancel, and profile
asynchronous threads
Derived Sheets
. Frequency Table (Shift+F) group rows by column value, with
aggregations of other columns
. Describe Sheet (Shift+I) view summary statistics for each column
. Pivot Table (Shift+W) group rows by key and summarize current
column
. Melted Sheet (Shift+M) unpivot non-key columns into
variable/value columns
. Transposed Sheet (Shift+T) open new sheet with rows and columns
transposed
INTERNAL SHEETS
Directory Sheet
(global commands)
Space open-dir-current
open the Directory Sheet for the current directory
(sheet-specific commands)
Enter gEnter open current/selected file(s) as new sheet(s)
^O g^O open current/selected file(s) in external $EDITOR
^R z^R gz^R reload information for all/current/selected file(s)
d gd delete current/selected file(s) from filesystem, upon
commit
y gy directory
copy current/selected file(s) to given directory,
upon commit
e ge name rename current/selected file(s) to name
` (backtick) open parent directory
z^S commit changes to file system
Guide Index
Browse through a list of available guides. Each guide shows you how to
use a particular feature. Gray guides have not been written yet.
(global commands)
Space open-guide-index
open the Guide Index
(sheet-specific commands)
Enter open a guide
Memory Sheet
Browse through a list of stored values, referanceable in expressions
through their name.
(global commands)
Alt+Shift+M open the Memory Sheet
Alt+M name store value in current cell in Memory Sheet under
name
(sheet-specific commands)
e edit either value or name, to edit reference
METASHEETS
Columns Sheet (Shift+C)
Properties of columns on the source sheet can be changed with standard
editing commands (e ge g= Del) on the Columns Sheet. Multiple aggregators
can be set by listing them (separated by spaces) in the aggregators
column. The 'g' commands affect the selected rows, which are the literal
columns on the source sheet.
(global commands)
gC open Columns Sheet with all visible columns from all
sheets
(sheet-specific commands)
& add column from appending selected source columns
g! gz! toggle/unset selected columns as key columns on
source sheet
g+ aggregator add Ar aggregator No to selected source columns
g- (hyphen) hide selected columns on source sheet
g~ g# g% g$ g@ gz# z%
set type of selected columns on source sheet to
str/int/float/currency/date/len/floatsi
Enter open a Frequency Table sheet grouped by column
referenced in current row
Sheets Sheet (Shift+S)
open Sheets Stack, which contains only the active sheets on the current
stack
(global commands)
gS open Sheets Sheet, which contains all sheets from
current session, active and inactive
Alt number jump to sheet number
(sheet-specific commands)
Enter jump to sheet referenced in current row
gEnter push selected sheets to top of sheet stack
a add row to reference a new blank sheet
gC gI open Columns Sheet/Describe Sheet with all visible
columns from selected sheets
g^R reload all selected sheets
z^C gz^C abort async threads for current/selected sheets(s)
g^S save selected or all sheets
& jointype merge selected sheets with visible columns from all,
keeping rows according to jointype:
. inner keep only rows which match keys on all
sheets
. outer keep all rows from first selected sheet
. full keep all rows from all sheets (union)
. diff keep only rows NOT in all sheets
. append combine all rows from all sheets
. concat similar to 'append' but keep first sheet
type and columns
. extend copy first selected sheet, keeping all rows
and sheet type, and extend with columns from other
sheets
. merge keep all rows from first sheet, updating
any False-y cells with non-False-y values from
second sheet; add unique rows from second sheet
Options Sheet (Shift+O)
(global commands)
Shift+O edit global options (apply to all sheets)
zO edit sheet options (apply to current sheet only)
gO open options.config as TextSheet
(sheet-specific commands)
Enter e edit option at current row
d remove option override for this context
^S save option configuration to foo.visidatarc
CommandLog (Shift+D)
(global commands)
D open current sheet's CommandLog with all other loose
ends removed; includes commands from parent sheets
gD open global CommandLog for all commands executed in
the current session
zD open current sheet's CommandLog with the parent
sheets commands' removed
(sheet-specific commands)
x replay command in current row
gx replay contents of entire CommandLog
^C abort replay
Threads Sheet (Ctrl+T)
(global commands)
^T open global Threads Sheet for all asynchronous
threads running
z^T open current sheet's Threads Sheet
(sheet-specific commands)
^C abort thread at current row
g^C abort all threads on current Threads Sheet
DERIVED SHEETS
Frequency Table (Shift+F)
A Frequency Table groups rows by one or more columns, and includes
summary columns for those with aggregators.
(global commands)
gF open Frequency Table, grouped by all key columns on
source sheet
zF open one-line summary for all rows and selected rows
(sheet-specific commands)
s t u select/toggle/unselect these entries in source sheet
Enter gEnter open copy of source sheet with rows that are grouped
in current cell / selected rows
Describe Sheet (Shift+I)
A Describe Sheet contains descriptive statistics for all visible columns.
(global commands)
gI open Describe Sheet for all visible columns on all
sheets
(sheet-specific commands)
zs zu select/unselect rows on source sheet that are being
described in current cell
! toggle/unset current column as a key column on source
sheet
Enter open a Frequency Table sheet grouped on column
referenced in current row
zEnter open copy of source sheet with rows described in cur‐
rent cell
Pivot Table (Shift+W)
Set key column(s) and aggregators on column(s) before pressing Shift+W on
the column to pivot.
(sheet-specific commands)
Enter open sheet of source rows aggregated in current pivot
row
zEnter open sheet of source rows aggregated in current pivot
cell
Melted Sheet (Shift+M)
Open Melted Sheet (unpivot), with key columns retained and all non-key
columns reduced to Variable-Value rows.
(global commands)
gM regex open Melted Sheet (unpivot), with key columns
retained and regex capture groups determining how the
non-key columns will be reduced to Variable-Value
rows.
Python Object Sheet (^X ^Y g^Y z^Y)
(sheet-specific commands)
Enter dive further into Python object
v toggle show/hide for methods and hidden properties
gv zv show/hide methods and hidden properties
COMMANDLINE OPTIONS
Add -n/--nonglobal to make subsequent CLI options sheet-specific
(applying only to paths specified directly on the CLI). By default, CLI
options apply to all sheets.
Options can also be set via the Options Sheet or a .visidatarc (see
FILES).
-P=longname preplay longname before replay or regular
launch; limited to Base Sheet bound commands
+toplevel:subsheet:row:col launch vd with subsheet of toplevel at
top-of-stack, and cursor at row and col; all
arguments are optional
--overwrite=c Overwrite with confirmation
--guides open Guide Index
-f, --filetype=filetype tsv set loader to use for
filetype instead of file extension
-d, --delimiter=delimiter \t field delimiter to use
for tsv/usv filetype
-y, --overwrite=y y overwrite existing files
without confirmation
-ro, --overwrite=n n do not overwrite existing
files
-N, --nothing=T False disable loading
.visidatarc and plugin addons
--visidata-dir=str ~/.visidata/ directory to load and
store additional files
--debug False exit on error and display
stacktrace
--undo=bool True enable undo/redo
--col-cache-size=int 0 max number of cache en‐
tries in each cached col‐
umn
--scroll-incr=int -3 amount to scroll with
scrollwheel
--force-256-colors False use 256 colors even if
curses reports fewer
--quitguard False confirm before quitting
modified sheet
--default-width=int 20 default column width
--default-height=int 4 default column height
--name-joiner=str _ string to join sheet or
column names
--value-joiner=str string to join display
values
--max-rows=int 1000000000 number of rows to load
from source
--wrap False wrap text to fit window
width on TextSheet
--save-filetype=str tsv specify default file type
to save as
--profile False enable profiling on
threads
--min-memory-mb=int 0 minimum memory to con‐
tinue loading and async
processing
--encoding=str utf-8-sig encoding passed to
codecs.open when reading
a file
--encoding-errors=str surrogateescape encoding_errors passed to
codecs.open
--mouse-interval=int 1 max time between
press/release for click
(ms)
--bulk-select-clear False clear selected rows be‐
fore new bulk selections
--some-selected-rows False if no rows selected, if
True, someSelectedRows
returns all rows; if
False, fails
--regex-skip=str regex of lines to skip in
text sources
--regex-flags=str I flags to pass to re.com‐
pile() [AILMSUX]
--load-lazy False load subsheets always
(False) or lazily (True)
--skip=int 0 skip N rows before header
--header=int 1 parse first N rows as
column names
--delimiter=str field delimiter to use
for tsv/usv filetype
--row-delimiter=str " row delimiter to use
for tsv/usv filetype
--tsv-safe-newline=str replacement for newline
character when saving to
tsv
--tsv-safe-tab=str replacement for tab char‐
acter when saving to tsv
--visibility=int 0 visibility level
--default-sample-size=int 100 number of rows to sample
for regex.split (0=all)
--fmt-expand-dict=str %s.%s format str to use for
names of columns expanded
from dict (colname, key)
--fmt-expand-list=str %s[%s] format str to use for
names of columns expanded
from list (colname, in‐
dex)
--json-indent=NoneType None indent to use when saving
json
--json-sort-keys False sort object keys when
saving to json
--json-ensure-ascii=bool True ensure ascii encode when
saving json
--default-colname=str column name to use for
non-dict rows
--filetype=str specify file type
--safe-error=str #ERR error string to use while
saving
--save-encoding=str utf-8 encoding passed to
codecs.open when saving a
file
--clean-names False clean column/sheet names
to be valid Python iden‐
tifiers
--replay-wait=float 0.0 time to wait between re‐
played commands, in sec‐
onds
--rowkey-prefix=str キ string prefix for rowkey
in the cmdlog
--clipboard-copy-cmd=str xclip -selection clipboard -filter
command to copy stdin to
system clipboard
--clipboard-paste-cmd=str xclip -selection clipboard -o
command to send contents
of system clipboard to
stdout
--fancy-chooser False a nicer selection inter‐
face for aggregators and
jointype
--null-value=NoneType None a value to be counted as
null
--histogram-bins=int 0 number of bins for his‐
togram of numeric columns
--numeric-binning False bin numeric columns into
ranges
--plot-colors=str list of distinct colors
to use for plotting dis‐
tinct objects
--motd-url=str source of randomized
startup messages
--dir-depth=int 0 folder recursion depth on
DirSheet
--dir-hidden False load hidden files on
DirSheet
--config=Path /home/saul/.visidatarc
config file to exec in
Python
--play=str file.vdj to replay
--batch False replay in batch mode
(with no interface and
all status sent to std‐
out)
--output=NoneType None save the final visible
sheet to output at the
end of replay
--preplay=str longnames to preplay be‐
fore replay
--imports=str plugins imports to preload before
.visidatarc (command-line
only)
--nothing False no config, no plugins,
nothing extra
--interactive False run interactive mode af‐
ter batch replay
--overwrite=str c overwrite existing files
{y=yes|c=confirm|n=no}
--plugins-autoload=bool True do not autoload plugins
if False
--theme=str display/color theme to
use
--airtable-auth-token=str Airtable API key from
https://airtable.com/ac‐
count
--matrix-token=str matrix API token
--matrix-user-id=str matrix user ID associated
with token
--matrix-device-id=str VisiData device ID associated with
matrix login
--reddit-client-id=str client_id for reddit api
--reddit-client-secret=str client_secret for reddit
api
--reddit-user-agent=str 3.1dev user_agent for reddit api
--zulip-batch-size=int -100 number of messages to
fetch per call (<0 to
fetch before anchor)
--zulip-anchor=int 1000000000 message id to start
fetching from
--zulip-delay-s=float 1e-05 seconds to wait between
calls (0 to stop after
first)
--zulip-api-key=str Zulip API key
--zulip-email=str Email for use with Zulip
API key
--csv-dialect=str excel dialect passed to
csv.reader
--csv-delimiter=str , delimiter passed to
csv.reader
--csv-doublequote=bool True quote-doubling setting
passed to csv.reader
--csv-quotechar=str " quotechar passed to
csv.reader
--csv-quoting=int 0 quoting style passed to
csv.reader and csv.writer
--csv-skipinitialspace=bool True skipinitialspace passed
to csv.reader
--csv-escapechar=NoneType None escapechar passed to
csv.reader
--csv-lineterminator=str " lineterminator passed
to csv.writer
--safety-first False sanitize input/output to
handle edge cases, with a
performance cost
--f5log-object-regex=NoneType None A regex to perform on the
object name, useful where
object names have a
structure to extract. Use
the (?P<foo>...) named
groups form to get column
names.
--f5log-log-year=NoneType None Override the default year
used for log parsing. Use
all four digits of the
year (e.g., 2022). By de‐
fault (None) use the year
from the ctime of the
file, or failing that the
current year.
--f5log-log-timezone=str UTC The timezone the source
file is in, by default
UTC.
--fixed-rows=int 1000 number of rows to check
for fixed width columns
--fixed-maxcols=int 0 max number of fixed-width
columns to create (0 is
no max)
--graphviz-edge-labels=bool True whether to include edge
labels on graphviz dia‐
grams
--grep-base-dir=NoneType None base directory for rela‐
tive paths opened with
sysopen-row
--html-title=str <h2>{sheet.name}</h2>
table header when saving
to html
--http-max-next=int 0 max next.url pages to
follow in http response
--http-req-headers=dict {} http headers to send to
requests
--http-ssl-verify=bool True verify host and certifi‐
cates for https
--npy-allow-pickle False numpy allow unpickling
objects (unsafe)
--pcap-internet=str n (y/s/n) if save_dot in‐
cludes all internet hosts
separately (y), combined
(s), or does not include
the internet (n)
--pdf-tables False parse PDF for tables in‐
stead of pages of text
--postgres-schema=str public The desired schema for
the Postgres database
--s3-endpoint=str alternate S3 endpoint,
used for local testing or
alternative S3-compatible
services
--s3-glob=bool True enable glob-matching for
S3 paths
--s3-version-aware False show all object versions
in a versioned bucket
--sqlite-onconnect=str sqlite statement to exe‐
cute after opening a con‐
nection
--xlsx-meta-columns False include columns for cell
objects, font colors, and
fill colors
--xlsx-color-cells=bool True color cells based on xlsx
source
--xml-parser-huge-tree=bool True allow very deep trees and
very long text content
--plt-marker=str . matplotlib.markers
--plot-palette=str Set3 colorbrewer palette to
use
--server-addr=str 127.0.0.1 IP address to listen for
commands
--server-port=int 0 port to listen for com‐
mands
--fixer-api-key=str API Key for api.api‐
layer.com/fixer
--fixer-cache-days=int 1 Cache days for currency
conversions
--describe-aggrs=str mean stdev numeric aggregators to
calculate on Describe
sheet
--hello-world=str ¡Hola mundo! shown by the hello-world
command
--incr-base=float 1.0 start value for column
increments
--ping-count=int 3 send this many pings to
each host
--ping-interval=float 0.1 wait between ping rounds,
in seconds
--regex-maxsplit=int 0 maxsplit to pass to
regex.split
--rename-cascade False cascade column renames
into expressions
--faker-locale=str en_US default locale to use for
Faker
--faker-extra-providers=NoneType None list of additional
Provider classes to load
via add_provider()
--faker-salt=str Use a non-empty string to
enable deterministic
fakes
--mailcap-mimetype=str force mimetype for
sysopen-mailcap
--unfurl-empty False if unfurl includes rows
for empty containers
DISPLAY OPTIONS
Display options can only be set via the Options Sheet or a .visidatarc
(see FILES).
disp_menu True show menu on top line when not
active
disp_menu_keys True show keystrokes inline in sub‐
menus
color_menu black on 68 blue color of menu items in general
color_menu_active 223 yellow on black
color of active menu items
color_menu_spec black on 34 green color of sheet-specific menu
items
color_menu_help black italic on 68 blue
color of helpbox
disp_menu_boxchars ││──┌┐└┘├┤ box characters to use for menus
disp_menu_more » command submenu indicator
disp_menu_push ⎘ indicator if command pushes sheet
onto sheet stack
disp_menu_input … indicator if input required for
command
disp_menu_fmt | VisiData {vd.version} | {vd.hintStatus}
right-side menu format string
disp_float_fmt {:.02f} default fmtstr to format float
values
disp_int_fmt {:d} default fmtstr to format int val‐
ues
disp_formatter generic formatter to create the text in
each cell (also used by text
savers)
disp_displayer generic displayer to render the text in
each cell
disp_splitwin_pct 0 height of second sheet on screen
disp_note_none ⌀ visible contents of a cell whose
value is None
disp_truncator … indicator that the contents are
only partially visible
disp_oddspace · displayable character for odd
whitespace
disp_more_left < header note indicating more col‐
umns to the left
disp_more_right > header note indicating more col‐
umns to the right
disp_error_val displayed contents for computa‐
tion exception
disp_ambig_width 1 width to use for unicode chars
marked ambiguous
disp_pending string to display in pending
cells
disp_note_pending : note to display for pending cells
disp_note_fmtexc ? cell note for an exception during
formatting
disp_note_getexc ! cell note for an exception during
computation
disp_note_typeexc ! cell note for an exception during
type conversion
color_note_pending bold green color of note in pending cells
color_note_type 226 yellow color of cell note for non-str
types in anytype columns
color_note_row 220 yellow color of row note on left edge
disp_column_sep │ separator between columns
disp_keycol_sep ║ separator between key columns and
rest of columns
disp_rowtop_sep │
disp_rowmid_sep ⁝
disp_rowbot_sep ⁝
disp_rowend_sep ║
disp_keytop_sep ║
disp_keymid_sep ║
disp_keybot_sep ║
disp_endtop_sep ║
disp_endmid_sep ║
disp_endbot_sep ║
disp_selected_note •
disp_sort_asc ↑↟⇞⇡⇧⇑ characters for ascending sort
disp_sort_desc ↓↡⇟⇣⇩⇓ characters for descending sort
color_default white on black the default fg and bg colors
color_default_hdr bold white on black
color of the column headers
color_bottom_hdr underline white on black
color of the bottom header row
color_current_row reverse color of the cursor row
color_current_col bold on 232 color of the cursor column
color_current_cell color of current cell, if differ‐
ent from color_cur‐
rent_row+color_current_col
color_current_hdr bold reverse color of the header for the cur‐
sor column
color_column_sep white on black color of column separators
color_key_col 81 cyan color of key columns
color_hidden_col 8 color of hidden columns on
metasheets
color_selected_row 215 yellow color of selected rows
color_clickable bold color of internally clickable
item
color_code bold white on 237 color of code sample
color_heading bold black on yellow
color of header
color_guide_unwritten 243 on black color of unwritten guides in
GuideGuide
disp_wrap_max_lines 3 max lines for multiline view
disp_wrap_break_long_words False break words longer than column
width in multiline
disp_wrap_replace_whitespace False replace whitespace with spaces in
multiline
disp_wrap_placeholder … multiline string to indicate
truncation
disp_multiline_focus True only multiline cursor row
color_aggregator bold 255 white on 234 black
color of aggregator summary on
bottom row
disp_rstatus_fmt {sheet.threadStatus} {sheet.keystrokeStatus}
[:longname_status]{sheet.longname}[/]
{sheet.nRows:9d} {sheet.rowtype}
{sheet.modifiedStatus}{sheet.selectedStatus}{vd.replayStatus}{vd.sidebarStatus}
right-side status format string
disp_status_fmt {sheet.sheetlist}|
left-side status format string
disp_lstatus_max 0 maximum length of left status
line
disp_status_sep │ separator between statuses
color_keystrokes bold white on 237 color of input keystrokes
color_longname_guide 237 color of command longnames
color_longname_status white color of command longnames
color_keys bold reverse color of keystrokes in help
color_status bold on 238 status line color
color_error 202 1 error message color
color_warning 166 15 warning message color
color_top_status underline top window status bar color
color_active_status black on 68 blue active window status bar color
color_inactive_status 8 on black inactive window status bar color
color_highlight_status black on green color of highlighted elements in
statusbar
color_working 118 5 color of system running smoothly
color_edit_unfocused 238 on 110 display color for unfocused input
in form
color_edit_cell 233 on 110 cell color to use when editing
cell
disp_edit_fill _ edit field fill character
disp_unprintable · substitute character for unprint‐
ables
disp_date_fmt %Y-%m-%d default fmtstr passed to strftime
for date values
disp_currency_fmt %.02f default fmtstr to format for cur‐
rency values
color_currency_neg red color for negative values in cur‐
rency displayer
disp_replay_play ▶ status indicator for active re‐
play
disp_replay_record ⏺ status indicator for macro record
color_status_replay green color of replay status indicator
disp_histogram ■ histogram element character
disp_graph_labels True show axes and legend on graph
disp_canvas_charset
⠀⠁⠂⠃⠄⠅⠆⠇⠈⠉⠊⠋⠌⠍⠎⠏⠐⠑⠒⠓⠔⠕⠖⠗⠘⠙⠚⠛⠜⠝⠞⠟⠠⠡⠢⠣⠤⠥⠦⠧⠨⠩⠪⠫⠬⠭⠮⠯⠰⠱⠲⠳⠴⠵⠶⠷⠸⠹⠺⠻⠼⠽⠾⠿⡀⡁⡂⡃⡄⡅⡆⡇⡈⡉⡊⡋⡌⡍⡎⡏⡐⡑⡒⡓⡔⡕⡖⡗⡘⡙⡚⡛⡜⡝⡞⡟⡠⡡⡢⡣⡤⡥⡦⡧⡨⡩⡪⡫⡬⡭⡮⡯⡰⡱⡲⡳⡴⡵⡶⡷⡸⡹⡺⡻⡼⡽⡾⡿⢀⢁⢂⢃⢄⢅⢆⢇⢈⢉⢊⢋⢌⢍⢎⢏⢐⢑⢒⢓⢔⢕⢖⢗⢘⢙⢚⢛⢜⢝⢞⢟⢠⢡⢢⢣⢤⢥⢦⢧⢨⢩⢪⢫⢬⢭⢮⢯⢰⢱⢲⢳⢴⢵⢶⢷⢸⢹⢺⢻⢼⢽⢾⢿⣀⣁⣂⣃⣄⣅⣆⣇⣈⣉⣊⣋⣌⣍⣎⣏⣐⣑⣒⣓⣔⣕⣖⣗⣘⣙⣚⣛⣜⣝⣞⣟⣠⣡⣢⣣⣤⣥⣦⣧⣨⣩⣪⣫⣬⣭⣮⣯⣰⣱⣲⣳⣴⣵⣶⣷⣸⣹⣺⣻⣼⣽⣾⣿
charset to render 2x4 blocks on
canvas
disp_pixel_random False randomly choose attr from set of
pixels instead of most common
disp_zoom_incr 2.0 amount to multiply current zoom‐
level when zooming
color_graph_hidden 238 blue color of legend for hidden attri‐
bute
color_graph_selected bold color of selected graph points
color_graph_axis bold color for graph axis labels
disp_graph_tick_x ╵ character for graph x-axis ticks
color_graph_refline color for graph reference value
lines
disp_graph_reflines_x_charset ▏││▕ charset to render vertical refer‐
ence lines on graph
disp_graph_reflines_y_charset ▔──▁ charset to render horizontal ref‐
erence lines on graph
disp_graph_multiple_reflines_char ▒ char to render multiple parallel
reflines
disp_expert 0 max level of options and columns
to include
color_add_pending green color for rows pending add
color_change_pending reverse yellow color for cells pending modifica‐
tion
color_delete_pending red color for rows pending delete
disp_sidebar True whether to display sidebar
disp_sidebar_fmt format string for default sidebar
disp_sidebar_width 0 max width for sidebar
disp_sidebar_height 0 max height for sidebar
color_sidebar black on 114 blue base color of sidebar
color_sidebar_title black on yellow color of sidebar title
color_match red color for matching chars in pal‐
ette chooser
color_f5log_mon_up green color of f5log monitor status up
color_f5log_mon_down red color of f5log monitor status
down
color_f5log_mon_unknown blue color of f5log monitor status un‐
known
color_f5log_mon_checking magenta color of monitor status checking
color_f5log_mon_disabled black color of monitor status disabled
color_f5log_logid_alarm red color of alarms
color_f5log_logid_warn yellow color of warnings
color_f5log_logid_notice cyan color of notice
color_f5log_logid_info green color of info
color_xword_active green color of active clue
color_cmdpalette black on 72 base color of command palette
disp_cmdpal_max 10 max number of suggestions for
command palette
disp_scroll_context 0 minimum number of lines to keep
visible above/below cursor when
scrolling
disp_sparkline ▁▂▃▄▅▆▇ characters to display sparkline
EXAMPLES
vd
launch DirSheet for current directory
vd foo.tsv
open the file foo.tsv in the current directory
vd -f ddw
open blank sheet of type ddw
vd new.tsv
open new blank tsv sheet named new
vd -f sqlite bar.db
open the file bar.db as a sqlite database
vd foo.tsv -n -f sqlite bar.db
open foo.tsv as tsv and bar.db as a sqlite database
vd -f sqlite foo.tsv bar.db
open both foo.tsv and bar.db as a sqlite database
vd -b countries.fixed -o countries.tsv
convert countries.fixed (in fixed width format) to countries.tsv (in tsv
format)
vd postgres://username:password@hostname:port/database
open a connection to the given postgres database
vd --play tests/pivot.vdj --replay-wait 1 --output tests/pivot.tsv
replay tests/pivot.vdj, waiting 1 second between commands, and output the
final sheet to test/pivot.tsv
ls -l | vd -f fixed --skip 1 --header 0
parse the output of ls -l into usable data
ls | vd | lpr
interactively select a list of filenames to send to the printer
vd newfile.tsv
open a blank sheet named newfile if file does not exist
vd sample.xlsx +:sheet1:2:3
launch with sheet1 at top-of-stack, and cursor at column 2 and row 3
vd -P open-plugins
preplay longname open-plugins before starting the session
FILES
At the start of every session, VisiData looks for $HOME/.visidatarc, and
calls Python exec() on its contents if it exists. For example:
options.min_memory_mb=100 # stop processing without 100MB free
bindkey('0', 'go-leftmost') # alias '0' to go to first column, like vim
def median(values):
L = sorted(values)
return L[len(L)//2]
vd.aggregator('median', median)
Functions defined in .visidatarc are available in python expressions
(e.g. in derived columns).
SUPPORTED SOURCES
Core VisiData includes these sources:
tsv (tab-separated value)
Plain and simple. VisiData writes tsv format by default. See the
--tsv-delimiter option.
csv (comma-separated value)
.csv files are a scourge upon the earth, and still regrettably
common.
See the --csv-dialect, --csv-delimiter, --csv-quotechar, and
--csv-skipinitialspace options.
Accepted dialects are excel-tab, unix, and excel.
fixed (fixed width text)
Columns are autodetected from the first 1000 rows (adjustable with
--fixed-rows).
json (single object) and jsonl/ndjson/ldjson (one object per line).
Cells containing lists (e.g. [3]) or dicts ({3}) can be expanded
into new columns with ( and unexpanded with ).
sqlite
May include multiple tables. The initial sheet is the table
directory; Enter loads the entire table into memory. z^S saves
modifications to source.
URL schemes are also supported:
http (requires requests); can be used as transport for with another
filetype
For a list of all remaining formats supported by VisiData, see
https://visidata.org/formats.
In addition, .zip, .gz, .bz2, .xz, ,zstd, and .zst files are decompressed
on the fly.
AUTHOR
VisiData was made by Saul Pwanson <[email protected]>.
Linux/MacOS October 13, 2024 Linux/MacOS