VisiData — a
terminal utility for exploring and arranging tabular data
vd |
[options] --play
cmdlog [-w
waitsecs] [--batch]
[-o output]
[field=value] |
vd |
[options] [input
...]
+toplevel:subsheet:col:row |
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 expressions; and
workflows can be saved, documented, and replayed.
-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
- --replay-movement
- toggle
--play to move cursor
cell-by-cell
- field
=value
- replace
"{field}" in
cmdlog contents with
value
- ^U
- pause/resume replay
- ^N
- execute next row in replaying sheet
- ^K
- cancel current replay
All keystrokes are case sensitive. The
^ prefix is shorthand for
Ctrl.
_ (underscore)- 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/currency/date/len
^- edit name of current column
g^- set names of all unnamed visible columns to contents of selected rows (or
current row)
z^- set name of current column to combined contents of current cell in
selected rows (or current row)
gz^- set name of all visible columns to combined contents of current 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 (iota)
- 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 evaluated
g'- open a frozen copy of current sheet with all visible columns
evaluated
z'
gz'- add/reset cache for current/all visible column(s)
: 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}) fully
z( gz(
depth- expand
current/all visible column(s) of lists (e.g.
[3]) or dicts (e.g. {3}) to given
depth (0= fully)
)- unexpand current column; restore original column and remove other columns
at this level
zM- row-wise
expand current column of lists (e.g. [3]) or
dicts (e.g. {3}) within that column
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
[ ]- 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 existing sort
criteria
gz[
gz]- sort ascending/descending by all key columns; add to existing 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
a za- append a blank row/column; appended columns cannot be copied to
clipboard
ga gza
number- append
number blank
rows/columns
d gd- delete (cut) current/selected row(s) and move to clipboard
y gy- yank (copy) current/all selected row(s) to clipboard
zy gzy- yank (copy) contents of current column for current/selected row(s) to
clipboard
zd gzd- delete (cut) contents of current column for current/selected row(s) and
move to clipboard
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
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
Enter ^C- accept/abort input
^O- open external $EDITOR to edit contents
^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- autocomplete input (when available)
Shift+Arrow- move cursor
in direction of Arrow and
re-enter edit mode
o input- open input in
VisiData
^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.vd- save
CommandLog to
filename.vd 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
&- concatenate top
two sheets in Sheets Stack
g&- concatenate
all sheets in Sheets Stack
+ -- increase/decrease zoom level, centered on cursor
_ (underscore)- zoom to fit full extent
z_
(underscore)- 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 contained within canvas
cursor
gs gt
gu- select/toggle/unselect rows on source sheet visible on screen
d- delete rows on source sheet contained within canvas 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
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^R- clear cache for current column
^Z- suspend VisiData process
^G- show cursor position and bounds of current sheet on status line
^V- show version and copyright information on status line
^P- open
Status History
- m keystroke
- first, begin
recording macro; second, prompt for keystroke
No, 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
stmt- execute
Python stmt in the
global scope
- (sheet-specific commands)
- (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)
- Browse through a list of available plugins. VisiData needs to be restarted
before plugin activation takes effect. Installation may require internet
access.
- (global commands)
Space
open-plugins- open the Plugins Sheet
- (sheet-specific commands)
a- install and activate current plugin
d- deactivate current plugin
- 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 concatenating 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
- 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
keep all rows from all sheets (concatenation)
- .
- extend
copy first selected sheet, keeping all rows and sheet
type, and extend with columns from other sheets
- .
- merge
mostly keep all rows from first selected sheet, except
prioritise cells with non-null/non-error values
- (global commands)
- (sheet-specific commands)
Enter e- edit option at current row
d- remove option override for this context
- (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
- 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
- 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 current cell
- 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
- 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.
- (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
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:col:row- launch vd
with subsheet of
toplevel at top-of-stack, and
cursor at col and
row; all arguments are optional
-f,
--filetype=filetype- tsv set loader to use for
filetype instead of file extension
-y,
--confirm-overwrite=F- True
overwrite existing files without confirmation
- --mouse-interval=int
1
- max time between press/release for click (ms)
- --null-value=NoneType
None
- a value to be counted as null
- --undo=bool
True
- enable undo/redo
- --col-cache-size=int
0
- max number of cache entries in each cached column
- --clean-names
False
- clean column/sheet names to be valid Python identifiers
- --default-width=int
20
- default column width
- --default-height=int
10
- default column height
- --textwrap-cells=bool
True
- wordwrap text for multiline rows
- --quitguard
False
- confirm before quitting last sheet
- --debug
False
- exit on error and display stacktrace
- --skip=int
0
- skip N rows before header
- parse first N rows as column names
- --load-lazy
False
- load subsheets always (False) or lazily (True)
- --force-256-colors
False
- use 256 colors even if curses reports fewer
- --use-default-colors
False
- curses use default terminal colors
- --note-pending=str
⌛
- note to display for pending cells
- --note-format-exc=str
?
- cell note for an exception during formatting
- --note-getter-exc=str
!
- cell note for an exception during computation
- --note-type-exc=str
!
- cell note for an exception during type conversion
- --scroll-incr=int
3
- amount to scroll with scrollwheel
- --name-joiner=str
_
- string to join sheet or column names
- --value-joiner=str
- string to join display values
- --wrap
False
- wrap text to fit window width on TextSheet
- --save-filetype=str
tsv
- specify default file type to save as
- --profile=str
- filename to save binary profiling data
- --min-memory-mb=int
0
- minimum memory to continue loading and async processing
- --input-history=str
- basename of file to store persistent input history
- --encoding=str
utf-8
- encoding passed to codecs.open
- --encoding-errors=str
surrogateescape
- encoding_errors passed to codecs.open
- --bulk-select-clear
False
- clear selected rows before new bulk selections
- --some-selected-rows
False
- if no rows selected, if True, someSelectedRows returns all rows; if False,
fails
- --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 character when saving to tsv
- --visibility=int
0
- visibility level (0=low, 1=high)
- --expand-col-scanrows=int
1000
- number of rows to check when expanding columns (0 = all)
- --json-indent=NoneType
None
- indent to use when saving json
- --json-sort-keys
False
- sort object keys when saving to json
- --default-colname=str
- column name to use for non-dict rows
- --filetype=str
- specify file type
- --confirm-overwrite=bool
True
- whether to prompt for overwrite confirmation on save
- --safe-error=str
#ERR
- error string to use while saving
- --clipboard-copy-cmd=str
- command to copy stdin to system clipboard
- --clipboard-paste-cmd=str
- command to get contents of system clipboard
- --fancy-chooser
False
- a nicer selection interface for aggregators and jointype
- --describe-aggrs=str
mean stdev
- numeric aggregators to calculate on Describe sheet
- --histogram-bins=int
0
- number of bins for histogram of numeric columns
- --numeric-binning
False
- bin numeric columns into ranges
- --replay-wait=float
0.0
- time to wait between replayed commands, in seconds
- --replay-movement
False
- insert movements during replay
- --visidata-dir=str
~/.visidata/
- directory to load and store additional files
- --rowkey-prefix=str
キ
- string prefix for rowkey in the cmdlog
- --cmdlog-histfile=str
- file to autorecord each cmdlog action to
- --regex-flags=str
I
- flags to pass to re.compile() [AILMSUX]
- --regex-maxsplit=int
0
- maxsplit to pass to regex.split
- --default-sample-size=int
100
- number of rows to sample for regex.split
- --show-graph-labels=bool
True
- show axes and legend on graph
- --plot-colors=str
- list of distinct colors to use for plotting distinct objects
- --zoom-incr=float
2.0
- amount to multiply current zoomlevel when zooming
- --motd-url=str
- source of randomized startup messages
- --dir-recurse
False
- walk source path recursively on DirSheet
- --dir-hidden
False
- load hidden files on DirSheet
- --config=str
~/.visidatarc
- config file to exec in Python
- --play=str
- file.vd to replay
- --batch
False
- replay in batch mode (with no interface and all status sent to
stdout)
- --output=NoneType
None
- save the final visible sheet to output at the end of replay
- --preplay=str
- longnames to preplay before replay
- --imports=str
plugins
- imports to preload before .visidatarc (command-line only)
- --incr-base=float
1.0
- start value for column increments
- --csv-dialect=str
excel
- dialect passed to csv.reader
- --csv-delimiter=str
,
- delimiter passed to csv.reader
- --csv-quotechar=str
"
- quotechar passed to csv.reader
- --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
- --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)
- --postgres-schema=str
public
- The desired schema for the Postgres database
- --http-max-next=int
0
- max next.url pages to follow in http response
- --html-title=str
<h2>{sheet.name}</h2>
- table header when saving to html
- --pcap-internet=str
n
- (y/s/n) if save_dot includes all internet hosts separately (y), combined
(s), or does not include the internet (n)
- --graphviz-edge-labels=bool
True
- whether to include edge labels on graphviz diagrams
- --pdf-tables
False
- parse PDF for tables instead of pages of text
- --plugins-url=str
https://visidata.org/plugins/plugins.jsonl
- source of plugins sheet
vd
foo.tsv
open the file foo.tsv in the current
directory
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/databasevd
--play tests/pivot.vd --replay-wait 1 --output
tests/pivot.tsv
replay tests/pivot.vd, 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
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]
aggregator('median', median)
Functions defined in .visidatarc are available in python
expressions (e.g. in derived columns).
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, and
.xz
files are decompressed on the fly.
These are the supported savers:
- tsv
(tab-separated value)
- csv
(comma-separated value)
- json
(one object with all rows)
- jsonl/ndjson/ldjson
(one object per line/row)
-
- All expanded subcolumns must be closed (with )) to
retain the same structure.
- sqlite
(save to source with z^S)
- md
(markdown table)