Skip to main content

Opening Files

VisiData auto-detects file formats from the extension and presents them as navigable sheets. When auto-detection fails, you specify the format explicitly with -f.

Learning Focus

Learn the four ways to get data into VisiData: file, directory, URL, and stdin pipe. Know when to use -f to override format detection.

Tool Snapshot
  • Command: vd [options] [file ...]
  • Format flag: -f filetype
  • Config override: ~/.visidatarc
  • Supported formats: 40+ (CSV, TSV, JSON, JSONL, SQLite, Parquet, Excel, fixed-width, HTML tables, and more)

Syntax & Expression Rules​

# Basic file open
vd filename.ext

# Open with explicit format
vd -f csv data.txt

# Open multiple files
vd file1.csv file2.json

# Open a URL directly
vd https://example.com/data.csv

# Open from stdin (pipe)
cat /var/log/nginx/access.log | vd -f fixed

# Open a directory (Directory Sheet)
vd /var/log/nginx/

# Open SQLite database
vd mydb.sqlite

# Open and immediately position cursor
vd data.csv +:sheetname:5:2    # sheet, row 5, col 2

Supported Format Auto-Detection​

ExtensionFormat loaded
.csvComma-separated values
.tsvTab-separated values
.jsonSingle JSON object or array
.jsonl / .ndjsonOne JSON object per line
.sqlite / .dbSQLite database (table directory)
.xlsx / .odsSpreadsheet
.log / .txtFixed-width or plain text
.parquetApache Parquet (requires pyarrow)
.htmlHTML tables on the page
.mdMarkdown tables
DirectoryDirectory Sheet (file browser)

Format Override with -f​

Use -f when the extension does not match the content:

# A .log file that is actually CSV
vd -f csv /var/log/app/requests.log

# A file with no extension
vd -f json api_response

# Treat output as fixed-width
ps aux | vd -f fixed --skip 0

# Open as TSV with custom delimiter
vd -f tsv -d '|' pipe_delimited.txt

Opening System Command Output​

# Inspect running processes interactively
ps aux | vd -f fixed --skip 1

# Analyze disk usage
df -h | vd -f fixed --skip 1

# Inspect open ports
ss -tulnp | vd -f fixed

# Browse nginx access log
vd /var/log/nginx/access.log

# Pipe from journalctl
journalctl -n 1000 --no-pager | vd -f txt

Opening Multiple Sheets at Launch​

# Open two sheets; use Shift+S to switch between them
vd servers.csv logs.json

# Open a database and a CSV together
vd mydb.sqlite extra_data.csv

Practical Use Cases​

Inspect a CSV Quickly​

vd /var/www/html/exports/orders.csv
# Expected: sheet opens with column headers auto-detected
# Row count shown in status bar (bottom right)

Open a SQLite Database​

vd /var/www/html/db/site.sqlite
# Expected: Directory sheet listing all tables
# Press Enter on a table to open it as a sheet

Browse a Log Directory​

vd /var/log/nginx/
# Expected: Directory Sheet showing file names, sizes, dates
# Press Enter to open any log file

Convert CSV to JSON (Batch Mode)​

vd -b input.csv -o output.json
# -b = batch mode (no interactive interface)
# -o = output file (format from extension)

Troubleshooting Matrix​

SymptomLikely CauseFix
Garbled columnsWrong delimiter detectedUse -f tsv or -d ','
File opens as plain textExtension not recognizedAdd -f csv or correct format
Encoding errorsNon-UTF-8 fileAdd --encoding latin1
SQLite tables missingOld VisiData versionpip install --upgrade visidata
URL fails to loadMissing requests modulepip install requests
Permission deniedFile not readablechmod 644 file or sudo vd file

Best Practices​

  • Always use -f explicitly in shell scripts — do not rely on auto-detection in automated workflows.
  • For large files, add --max-rows 10000 to inspect a sample without loading everything.
  • Open log files with vd -f fixed --skip 1 to skip the header line from commands like ps aux.
  • Use vd -b (batch mode) for automated data conversion without the TUI.

Hands-On Practice​

# Practice opening different sources:

# 1. Open a CSV
curl -o /tmp/data.csv https://people.sc.fsu.edu/~jburkardt/data/csv/addresses.csv
vd /tmp/data.csv

# 2. Open a log file
vd /var/log/syslog

# 3. Pipe command output
df -h | vd -f fixed

# 4. Open a directory
vd /var/log/

What's Next​