Reading and Writing Tabular Data

The format-specific functions share one naming scheme: read or write, then the container that holds the data in MATLAB. They determine the file format from the file extension (or from the FileType name-value argument when the extension does not say).

The "Introduced" column gives the release of the reader, from the "Version History" of its reference page (detectImportOptions is R2016b); the release of each writer was not looked up. When the data is not column-oriented (a header block, free-form lines, a binary layout), the low-level functions or textscan are the tools.

The table below is a trimmed form of the table on the "Supported File Formats for Import and Export" page, keeping the rows relevant to tabular data. The full page also lists images, audio, video, scientific formats (CDF, FITS, HDF, HDF5, netCDF) and STL.

Source: MATLAB documentation: Supported File Formats for Import and Export

Two rows of that table are not the whole story. readtable reads more than the table shows (JSON since R2026a, HTML and Microsoft Word documents since R2021b, as the sections below explain), and writetable writes JSON and XML as well as text and spreadsheets. The authoritative lists are on the reference pages of the functions.

The heatflow scenario (The heatflow scenario) logs thermocouple readings to data/sensors.csv. The listing is the illustrative sample used on Timetables; the real file is longer, and the logger leaves a field empty when a reading is lost:

The page uses this file for every example. The shortest way to read it is also the first thing to try:

Not run here. readtable reads the first line as variable names (Time, SensorID, Temperature), detects that the first column holds dates and times and that the third holds numbers, and fills the empty field with NaN. The sections below take that default apart and show each step you can change.

Source: MATLAB documentation: readtable

T = readtable(filename) creates a table from a text, spreadsheet, JSON (R2026a), XML, HTML or Microsoft Word file. The four forms of the call:

The file name can be a relative or absolute path, a file on the MATLAB path, an http:// or https:// URL, or a remote location (Amazon S3, Azure Blob Storage, HDFS). Since R2026b S3 and Azure locations can also be given as https:// URLs. A name without an extension needs FileType ("text", "delimitedtext", "fixedwidth", "spreadsheet", "json", "xml", "worddocument" or "html").

When the name-value arguments are not enough, create an import options object. It is a configuration that describes how to read one kind of file; you can inspect it, change it, apply it to many files, and keep it as a file-reading recipe.

opts = detectImportOptions(filename) locates the table in a file and returns the matching object. The class depends on the file:

detectImportOptions accepts the same table-level name-value arguments as readtable (Delimiter, NumHeaderLines, Sheet, VariableNamingRule, MissingRule, ImportErrorRule, DecimalSeparator, and many more), so they customise the detection itself. The object is then edited at two levels.

Table level: assign properties of opts. The most useful are VariableNames, VariableTypes, SelectedVariableNames (which variables to import), DataLines (for text, for example [2 Inf]), VariableNamesLine, Delimiter, MissingRule, ImportErrorRule and VariableNamingRule; for spreadsheets DataRange and VariableNamesRange replace the line properties. preview(filename,opts) shows the first rows of the result without reading everything.

Variable level: use three functions, which take variable names (or positions) and return a modified copy of the object.

Not run here. The detected types are typically datetime, char and double; after the edits Time is a zoned datetime, SensorID is a categorical array, Temperature is single with -999 read as missing, and the same opts can read every other file in the folder that has this layout. The InputFormat is the one used on Dates and Times; a format that does not match makes the import produce NaT unless ImportErrorRule says otherwise. The object stores types as the names MATLAB reports in opts.VariableTypes (double, char, string, categorical, datetime, logical, …​).

Source: MATLAB documentation: setvartype

TT = readtimetable(filename) is readtable with a timestamp promoted to row times: the first datetime or duration column becomes the row times, and the rest become the variables. It accepts text, spreadsheet, JSON (R2026a), XML and compressed files, and an options object from detectImportOptions. Alongside an options object it honours ReadVariableNames, RowTimes, SampleRate, TimeStep and StartTime (and DateLocale, Encoding, Sheet and UseExcel where they apply).

Not run here. TT is a 6-by-2 timetable with the variables SensorID and Temperature. The TT2 call assumes a file with only data columns and builds row times at 2 samples per second starting at zero; RowTimes names an existing variable (or supplies a vector) when the first date column is not the one you want. A timestamp that MATLAB cannot recognise needs setvaropts with InputFormat first, as shown above. The subsequent work (retime, synchronize, resample) is on Timetables.

Source: MATLAB documentation: readtimetable

When the file holds only numbers, a table is more than you need.

A = readmatrix(filename) returns a numeric array. It detects the delimiter and the header lines and skips what is not numeric. OutputType chooses another type, Range limits the region, NumHeaderLines skips lines, TreatAsMissing names missing placeholders, Delimiter, DecimalSeparator, ThousandsSeparator, TrimNonNumeric, CommentStyle and the delimiter rules handle awkward text, and Sheet and Range select the spreadsheet region. An options object is allowed here too.

C = readcell(filename) reads every element into one cell of a cell array and keeps its own type: numbers as numbers, text as character vectors, dates as datetime, and gaps as missing or NaN. It is the right tool for a sheet that does not form a table: mixed blocks, notes, titles above the data. The documentation example reads ten rows of columns G to I from the sheet named "2007" of a workbook with one sheet per year: readcell("airlinesmall_subset.xlsx",Sheet="2007",Range="G2:I11").

[Var1,...,VarN] = readvars(filename) returns one workspace variable per column and is convenient to unpack two or three columns without a table.

Not run here. temps and block are numeric matrices of the temperature field (the file name is illustrative); raw is a 7-by-3 cell array whose first row holds the header text and whose empty temperature field is a missing value; t, id and temp are the three columns (datetime, text, double). To choose the types of the outputs of readmatrix, readcell or readvars, pass an opts object as the second input.

Source: MATLAB documentation: readmatrix, readcell, readvars

The writers mirror the readers. writetable(T,filename) chooses the format from the extension: .txt, .dat or .csv for delimited text; .xls, .xlsm or .xlsx for spreadsheets (.xlsb only with Excel for Windows); .json and .xml. writetable(T) with no file name writes a text file named after the workspace variable and ending in .txt.

Not run here. The first call writes the variable names on the first line and one line per row. The second asks for a tab delimiter (the .tsv extension is not one the function recognises, hence FileType="text"). The third quotes every text field. The fourth appends to an existing file without repeating the header (the documentation says append and WriteVariableNames=true cannot be combined for spreadsheets). The last writes into the sheet S1 of a workbook starting at cell B2.

Source: MATLAB documentation: writetable

The name-value arguments of writetable:

writematrix(A,filename) writes a homogeneous array to a text or spreadsheet file; it overwrites an existing text file unless WriteMode="append", accepts Delimiter, QuoteStrings, Encoding, Sheet, Range and the spreadsheet options, and does not support sparse matrices. writecell and writetimetable do the same for cell arrays and timetables.

A spreadsheet is a container of sheets, each a grid of cells. The readers and writers take the same two arguments for locating data:

Not run here. The first read takes the first row as variable names; the second reads a 5-by-3 block starting at C2 and names its variables Var1 to Var3, because the first row of the range is data; runs holds one table per sheet. With an opts object, set the area on the object (opts.Sheet, opts.DataRange, opts.VariableNamesRange) so the same recipe is reusable, as in the documentation’s patients.xls example where opts.SelectedVariableNames restricts the read to two columns.

Source: MATLAB documentation: Spreadsheets

Points that decide whether spreadsheet code works on a given machine:

Since R2026b the same functions read and write Google Sheets spreadsheets. The functions named in the release notes are readtable, writetable, readmatrix, writematrix, readcell, writecell, readtimetable, writetimetable and sheetnames; instead of a file name, pass the spreadsheet URL or the spreadsheet ID. Sheet and Range choose the region.

Not run here. <SPREADSHEET_ID> is a placeholder; use your own spreadsheet. Before the first call, authorise MATLAB once (the steps, in short):

The client secret in that JSON file is a credential: keep it out of the repository and out of your code, and see Secrets and Protecting Code. The documentation lists the following limits: going over Google’s quota limit is an error; a spreadsheet may hold at most 10 million cells across all sheets, and a write can fail past it; a new spreadsheet cannot be created programmatically in a Shared drive (create it by hand first); and writing wide tables can be slow when columns are auto-fitted, which AutoFitWidth=false avoids.

Sources: MATLAB documentation: Read and Write Data from Your Google Account, MATLAB release notes

readtable is a general front end for "table-like data", and the list has grown with the releases (all from the Version History of the reference page):

JSON as a table is the same R2026a feature described with readstruct and jsondecode on JSON, XML and Web Access. A weboptions object can be passed with WebOptions when the URL needs headers or credentials; do not put real credentials in code (use secretID objects or environment variables, and placeholders in published examples).

The Import Tool is the interactive front end to the same functions. It previews a file (or the clipboard), lets you select rows, columns or variables, rename variables, set their types, replace unimportable or empty cells, and then imports the data, or generates code (a script or a function) that reproduces the import. That generated function is a convenient way to learn the options object for a file you will read repeatedly.

The tool is convenient for exploration. Production code should call the functions, because a script that opens a dialog is not reproducible. Use the Import Tool to find the settings, copy the generated code, and keep that.

Sources: MATLAB documentation: Import Tool, Text Files, Spreadsheets

The functions on this page are not part of the minimal core of the language that Octave implements. For small, regular files the low-level tools work in MATLAB and in Octave, and are what the snippet below uses: fprintf writes the file and textscan reads formatted columns into a cell array. See Low-Level File I/O and the File System for fopen, fprintf and textscan in detail.

Octave 11.3.0 output (MATLAB’s layout may differ in spacing):

The run reads the six-row sensors.csv as three columns (the third as numbers, with the empty field read as NaN through EmptyValue) and counts the one gap. The temporary folder is created inside the working directory and removed at the end. In MATLAB, the same job is readtable and needs no format string. A purely numeric matrix goes through a CSV file with writematrix and readmatrix, the replacements for the older dlmwrite, dlmread and csvwrite:

The exact messages and identifiers depend on the release and were not run here; the descriptions give the cause.