csvwrite — Write numeric matrices to CSV files in MATLAB and RunMat.
csvwrite(filename, M) writes numeric matrices to comma-separated text files. Legacy row/column offset arguments follow MATLAB and RunMat compatibility semantics.
Syntax
csvwrite(filename, M)
csvwrite(filename, M, row, col)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
filename | StringScalar | Yes | — | CSV output path. |
M | Any | Yes | — | Numeric/logical matrix data to write. |
row | IntegerScalar | Yes | — | Zero-based row offset before writing values. |
col | IntegerScalar | Yes | — | Zero-based column offset before writing values. |
Errors
| Identifier | When | Message |
|---|---|---|
| — | Filename argument is not a scalar string/char vector. | csvwrite: invalid filename input |
| — | Filename resolves to an empty string. | csvwrite: filename must not be empty |
| — | Offset arguments are missing, malformed, or out of bounds. | csvwrite: invalid row/column offsets |
| — | Input data cannot be converted to a numeric/logical tensor. | csvwrite: input must be numeric or logical |
| — | Input data is not a 2-D matrix. | csvwrite: input must be 2-D |
| — | Output file cannot be opened. | csvwrite: unable to open file for writing |
| — | Output file write/flush fails. | csvwrite: write failed |
How csvwrite works
- Real or complex single/double data, all eight real integer classes, and logical matrices are accepted. Integer values serialize directly from authoritative storage; logical values serialize as
0and1. csvwrite(filename, M, row, col)starts writing at zero-based rowrowand columncol, leaving earlier rows blank and earlier columns empty within each row. Offsets must be non-negative integers.- Matrices must be 2-D (trailing singleton dimensions are ignored). Column-major ordering is respected when serialising to text.
- Numbers are emitted using MATLAB-compatible short
gformatting (%.5g).NaN,Inf, and-Inftokens are written verbatim. - Each row ends with LF (
\n) on every platform. Existing files are overwritten; usewritematrixwith'WriteMode','append'when append behavior is required. - The documented form has no output. RunMat can return a bytes-written output only when the
csvwrite-bytes-written-outputextension is enabled. - Paths that begin with
~expand to the user's home directory before writing.
Does RunMat run csvwrite on the GPU?
csvwrite always executes on the host CPU. With the resident-input extension enabled, RunMat gathers through the handle owner before serialisation. A bytes-written return value is a separately gated extension.
GPU memory and residency
With the csvwrite-resident-input extension enabled, resident data is gathered through the handle's owning provider before host file I/O. Strict compatibility mode rejects the extension before provider access or file mutation.
Examples
Writing a numeric matrix to CSV
A = [1 2 3; 4 5 6];
csvwrite("scores.csv", A)Starting output after a header row
fid = fopen("with_header.csv", "w");
fprintf(fid, "Name,Jan,Feb\nalpha,1,2\nbeta,3,4\n");
fclose(fid);
csvwrite("with_header.csv", [10 20; 30 40], 1, 0)Skipping leading columns before data
B = magic(3);
csvwrite("offset_columns.csv", B, 0, 2)Exporting logical masks as numeric zeros and ones
mask = [true false true; false true false];
csvwrite("mask.csv", mask)Writing resident data and returning a byte count
% Requires both csvwrite-resident-input and csvwrite-bytes-written-output.
G = gpuArray(single([0.1 0.2 0.3]));
bytes = csvwrite("gpu_values.csv", G)Expected output:
bytes = 12Persisting a scalar value for downstream tools
total = sum(rand(5));
csvwrite("scalar.csv", total)Using csvwrite with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how csvwrite changes the result.
Run a small csvwrite example, explain the result, then change one input and compare the output.
FAQ
Why must the input be numeric or logical?⌄
csvwrite predates MATLAB's table and string support and only serialises numeric values. Provide numeric matrices or logical masks, or switch to writematrix when you need to mix text and numbers.
Are row and column offsets zero-based?⌄
Yes. row = 1 skips one full line before writing, and col = 2 inserts two empty comma-separated fields at the start of each written row.
Can I append to an existing CSV with csvwrite?⌄
No. csvwrite always overwrites the destination file. Use writematrix with 'WriteMode','append' or manipulate the file with lower-level I/O functions.
How are NaN and Inf values written?⌄
They are emitted verbatim as NaN, Inf, or -Inf, matching MATLAB's text representation so that downstream tools can parse them consistently.
What line ending does csvwrite use?⌄
The builtin always writes LF (\n), including on Windows.
Related Io functions
Tabular
arrayDatastore · csvread · detectImportOptions · dlmread · dlmwrite · fileDatastore · parquetDatastore · parquetinfo · parquetread · readcell · readmatrix · readtable · readtimetable · spreadsheetImportOptions · writecell · writematrix · writetable · writetimetable · xlsread · xlswrite
Repl Fs
addpath · cd · copyfile · delete · dir · exist · fileattrib · fileparts · fullfile · genpath · getenv · getpref · isenv · isfile · isfolder · ispref · ls · matlabroot · memmapfile · mkdir · movefile · open · opentoline · path · pathsep · pcode · pwd · readstruct · rehash · restoredefaultpath · rmdir · rmpath · run · savepath · setenv · setpref · system · tempdir · tempname · uigetdir · uigetfile · uiputfile · unsetenv · userpath · what · winqueryreg · xmlread · xmlwrite
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite · readlines · writelines
Import
Json
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how csvwrite is executed, line by line, in Rust.
- View the source for csvwrite 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.