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
bytesWritten = csvwrite(filename, M)
bytesWritten = 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. |
Returns
| Name | Type | Description |
|---|---|---|
bytesWritten | NumericScalar | Number of bytes written to the output file. |
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
- Only real numeric or logical inputs are accepted. Logical values are converted to
0and1before writing. Complex and textual inputs raise descriptive errors. 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. - Existing files are overwritten.
csvwritedoes not support appending; switch towritematrixwith'WriteMode','append'when the behaviour is required. - 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. When the matrix resides on the GPU, RunMat gathers the data through the active acceleration provider before serialisation. No provider hooks are required, and the return value reports the number of bytes written after the gather completes.
GPU memory and residency
No additional steps are necessary. csvwrite treats GPU arrays as residency sinks: data is gathered back to host memory prior to writing. This matches MATLAB's behaviour, where file I/O always operates on host-resident values.
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 GPU-resident data without manual gather
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 uses the platform default (\r\n on Windows, \n elsewhere). Most CSV consumers handle either convention transparently.
Related Io functions
Tabular
csvread · dlmread · dlmwrite · readmatrix · writematrix
Repl Fs
addpath · cd · copyfile · delete · dir · exist · fullfile · genpath · getenv · ls · mkdir · movefile · path · pwd · rmdir · rmpath · run · savepath · setenv · tempdir · tempname
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite
Json
Http
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.