xlsread — Read numeric, text, and raw data from spreadsheet files.
xlsread imports spreadsheet data using MATLAB's legacy call forms. The first output is a dense double matrix; optional second and third outputs return text cells and raw cells.
Syntax
num = xlsread(filename)
num = xlsread(filename, sheetOrRange)
num = xlsread(filename, sheet, range)
num = xlsread(filename, sheet, range, '-basic')
[num, txt, raw] = xlsread(___)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
filename | StringScalar | Yes | — | Spreadsheet file path. |
sheetOrRange | Any | Yes | — | Worksheet name/index or Excel range. |
sheet | Any | Yes | — | Worksheet name or one-based index. |
range | StringScalar | Yes | — | Excel A1 range. |
mode | StringScalar | No | "basic" | Legacy '-basic' compatibility flag. |
Returns
| Name | Type | Description |
|---|---|---|
num | NumericArray | Numeric worksheet data. |
txt | Any | Text worksheet cells. |
raw | Any | Raw worksheet cells. |
Returned values from xlsread depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:xlsread:InvalidArgument | Argument list does not match supported xlsread call forms. | xlsread: invalid argument |
RunMat:xlsread:Filename | Filename is invalid or cannot be normalized. | xlsread: invalid filename |
RunMat:xlsread:Range | Range specification is malformed or semantically invalid. | xlsread: invalid range |
RunMat:xlsread:Sheet | Requested worksheet is missing or invalid. | xlsread: invalid sheet |
RunMat:xlsread:Io | Spreadsheet cannot be opened or read. | xlsread: unable to read spreadsheet |
RunMat:xlsread:OutputCount | Caller requests more outputs than xlsread supports. | xlsread: unsupported output count |
RunMat:xlsread:TensorBuild | Output arrays cannot be materialized. | xlsread: unable to construct output |
How xlsread works
xlsread(filename)reads the first worksheet. If the filename has no extension,.xlsxis appended.xlsread(filename, range)reads an Excel A1 range such as"C4:C19"from the first worksheet.xlsread(filename, sheet)selects a worksheet by name or one-based numeric index.xlsread(filename, sheet, range)combines worksheet and range selection.- The legacy
'-basic'mode flag is accepted as a no-op because RunMat always uses its host spreadsheet parser rather than Excel COM automation. - The numeric output trims leading and trailing rows/columns that contain no numeric cells, then fills nonnumeric cells inside the numeric rectangle with
NaN. [num, txt, raw] = xlsread(...)returns text cells intxtand mixed number/string/logical cells inraw.- Excel callback/process-function modes are not supported and raise a descriptive argument error.
Does RunMat run xlsread on the GPU?
xlsread performs file I/O and spreadsheet parsing on the CPU. It is not fusible and does not call acceleration provider hooks.
GPU memory and residency
xlsread always creates host values. Move the numeric output to the GPU explicitly with gpuArray if later computation should run on the active acceleration provider.
Examples
Read one spreadsheet column
V = xlsread('diod.xlsx', 'C4:C19');
plot(V)Read a named worksheet and range
I = xlsread('measurements.xlsx', 'Data', 'D4:D19');Capture numeric, text, and raw outputs
[num, txt, raw] = xlsread('measurements.xlsx', 'A1:C10');Using xlsread with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how xlsread changes the result.
Run a small xlsread example, explain the result, then change one input and compare the output.
FAQ
Which spreadsheet formats are supported?⌄
RunMat uses the same spreadsheet reader as readtable, covering common Excel/OpenDocument formats handled by the runtime parser, including .xls, .xlsx, .xlsm, .xlsb, and .ods.
Does xlsread use Microsoft Excel?⌄
No. RunMat reads spreadsheets directly on the host. The '-basic' compatibility flag is accepted, but COM automation and Excel callback processing are not part of RunMat's runtime model.
What should I use for new code?⌄
xlsread exists for legacy MATLAB compatibility. For new mixed-type imports, prefer readtable; for numeric matrices, readmatrix is the modern MATLAB API.
Related Io functions
Tabular
csvread · csvwrite · detectImportOptions · dlmread · dlmwrite · readmatrix · spreadsheetImportOptions · writecell · writematrix
Repl Fs
addpath · cd · copyfile · delete · dir · exist · fullfile · genpath · getenv · ls · mkdir · movefile · path · pwd · rmdir · rmpath · run · savepath · setenv · tempdir · tempname · uigetfile · uiputfile
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite
Import
Json
Archive
Http
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how xlsread is executed, line by line, in Rust.
- View the source for xlsread in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.