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.
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
g/ g?
regex- search
for regex
forward/backward over all visible columns
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/bottom/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
_ (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/currency/date/len
^- rename current column
g^- rename all unnamed visible columns to contents of selected 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 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
- 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}) 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)
)- 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
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.
Enter ^C- accept/abort input
^O
g^O- open external $EDITOR to edit contents of current/selected 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- autocomplete input (when available)
Shift+Arrow- move cursor
in direction of Arrow and
re-enter edit mode
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
+ -- 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 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- 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 , 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
- (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
- 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
- Browse through a list of stored values, referanceable in
expressions through their
name.
- (global commands)
- (sheet-specific commands)
e- edit either value or name, to edit reference
- 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
- 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
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
^S- save option configuration to
foo.visidatarc
- (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
- (global commands)
^T- open global Threads Sheet
for all asynchronous threads running
z^T- open current sheet's Threads
Sheet
- (sheet-specific commands)
- 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
-d,
--delimiter=delimiter- \t field delimiter to use for tsv/usv
filetype
-y,
--confirm-overwrite=F- True
overwrite existing files without confirmation
-N,
--nothing=T- False
disable loading .visidatarc and plugin addons
- --visidata-dir=str
~/.visidata/
- directory to load and store additional files
- --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
4
- default column height
- --textwrap-cells=bool
True
- wordwrap text for multiline rows
- --quitguard
False
- confirm before quitting modified 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
- --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
False
- enable profiling on threads
- --min-memory-mb=int
0
- minimum memory to continue loading and async processing
- --encoding=str
utf-8
- encoding passed to codecs.open
- --encoding-errors=str
surrogateescape
- encoding_errors passed to codecs.open
- --input-history=str
- basename of file to store persistent input history
- --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)
- --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,
index)
- --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
- --replay-wait=float
0.0
- time to wait between replayed commands, in seconds
- --replay-movement
False
- insert movements during replay
- --rowkey-prefix=str
キ
- string prefix for rowkey in the cmdlog
- --cmdlog-histfile=str
- file to autorecord each cmdlog action to
- --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
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 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
- --regex-flags=str
I
- flags to pass to re.compile() [AILMSUX]
- --regex-maxsplit=int
0
- maxsplit to pass to 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=Path
/home/kefala/.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)
- --nothing
False
- no config, no plugins, nothing extra
- --unfurl-empty
False
- if unfurl includes rows for empty containers
- --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
- --xlsx-meta-columns
False
- include columns for cell objects, font colors, and fill colors
- --sqlite-onconnect=str
- sqlite statement to execute after opening a connection
- --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
- http headers to send to requests
- --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)
- --xml-parser-huge-tree=bool
True
- allow very deep trees and very long text content
- --graphviz-edge-labels=bool
True
- whether to include edge labels on graphviz diagrams
- --npy-allow-pickle
False
- numpy allow unpickling objects (unsafe)
- --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
- --plugins-autoload=bool
True
- do not autoload plugins if False
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/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]
vd.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,
.xz,
,zstd,
and .zst
files are decompressed on the fly.