xlswrite

(Not recommended) Write spreadsheet file

xlswrite is not recommended. Use writetable, writematrix, or writecell instead. For more information, see Compatibility Considerations.

Syntax

xlswrite(filename,A)

xlswrite(filename,A,sheet)

xlswrite(filename,A,xlRange)

xlswrite(filename,A,sheet,xlRange)

status = xlswrite(___)

[status,message] = xlswrite(___)

Description

xlswrite(filename,A) writes matrix A to the first worksheet in the Microsoft^® Excel^® spreadsheet workbook filename starting at cell A1.

xlswrite(filename,A,sheet) writes to the specified worksheet.

xlswrite(filename,A,xlRange) writes to the rectangular region specified by xlRange in the first worksheet of the workbook. Use Excel range syntax, such as 'A1:C3'.

xlswrite(filename,A,sheet,xlRange) writes to the specified worksheet and range.

status = xlswrite(___) returns the status of the write operation, using any of the input arguments in previous syntaxes. When the operation is successful, status is 1. Otherwise, status is 0.

[status,message] = xlswrite(___) additionally returns any warning or error message generated by the write operation in structure message.

Examples

Write Vector to Spreadsheet

Write a 7-element vector to an Excel® file.

filename = 'testdata.xlsx';
A = [12.7 5.02 -98 63.9 0 -.2 56];
xlswrite(filename,A)

Write to Specific Sheet and Range in Spreadsheet

Write mixed text and numeric data to an Excel® file starting at cell E1 of Sheet2.

filename = 'testdata.xlsx';
A = {'Time','Temperature'; 12,98; 13,99; 14,97};
sheet = 2;
xlRange = 'E1';
xlswrite(filename,A,sheet,xlRange)

Input Arguments

filename — File name

character vector | string

File name, specified as a character vector or a string.

If filename does not exist, xlswrite creates a file, determining the format based on the specified extension. To create a file compatible with Excel 97-2003 software, specify an extension of .xls. To create files in Excel 2007 formats, specify an extension of .xlsx, .xlsb, or .xlsm. If you do not specify an extension, xlswrite uses the default, .xls.

Example: 'myFile.xlsx' or "myFile.xlsx"

Example: 'C:\myFolder\myFile.xlsx'

Example: 'myFile.csv'

Data Types: char | string

A — Input matrix

matrix

Input matrix, specified as a two-dimensional numeric, character array, or string array, or, if each cell contains a single element, a cell array.

If A is a cell array containing something other than a scalar numeric or text, then xlswrite silently leaves the corresponding cell in the spreadsheet empty.

The maximum size of array A depends on the associated Excel version. For more information on Excel specifications and limits, see the Excel help.

Example: [10,2,45;-32,478,50]

Example: {92.0,'Yes',45.9,'No'}

Example: "ABCDEF"

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64 | logical | char | string | cell

sheet — Worksheet name

character vector | string | positive integer

Worksheet name, specified as one of the following:

• Character vector or string that contains the worksheet name. The name cannot contain a colon (:). To determine the names of the sheets in a spreadsheet file, use xlsfinfo.

• Positive integer that indicates the worksheet index.

If sheet does not exist, xlswrite adds a new sheet at the end of the worksheet collection. If sheet is an index larger than the number of worksheets, xlswrite appends empty sheets until the number of worksheets in the workbook equals sheet. In either case, xlswrite generates a warning indicating that it has added a new worksheet.

Data Types: char | string | single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

xlRange — Rectangular range

character vector | string

Rectangular range, specified as a character vector or a string.

Specify xlRange using two opposing corners that define the region to write. For example, 'D2:H4' represents the 3-by-5 rectangular region between the two corners D2 and H4 on the worksheet. The xlRange input is not case sensitive, and uses Excel A1 reference style (see Excel help). xlswrite does not recognize named ranges.

• If you do not specify sheet, then xlRange must include both corners and a colon character, even for a single cell (such as 'D2:D2'). Otherwise, xlswrite interprets the input as a worksheet name (such as 'D2').

• If you specify sheet, then xlRange can specify only the first cell (such as 'D2'). xlswrite writes input array A beginning at this cell.

• If xlRange is larger than the size of input array A, Excel software fills the remainder of the region with #N/A. If xlRange is smaller than the size of A, then xlswrite writes only the subset that fits into xlRange to the file.

Data Types: char | string

Output Arguments

status — Status of the write operation

1 | 0

Status of the write operation, returned as either 1 (true) or 0 (false). When the write operation is successful, status is 1. Otherwise, status is 0.

message — Error or warning generated during the write operation

structure array

Error or warning generated during the write operation, returned as a structure array containing two fields:

message	Text of the warning or error message.
identifier	Message identifier.

Limitations

• The xlswrite function does not support writing cell arrays that contain different data types when attempting to write CSV files.

• If your computer does not have Excel for Windows^® or you are using MATLAB^® Online™, then the xlswrite function:

  • Writes array A to a text file in comma-separated value (CSV) format. A must be a numeric matrix.

  • Ignores the sheet and xlRange arguments.

  This limitation also applies when the COM server (part of the typical installation of Excel) is not available.

Tips

• If your computer has Microsoft Office 2003 software, but you want to create a file in an Excel 2007 format, install the Office 2007 Compatibility Pack.

• Excel and MATLAB can store dates as text that represents those dates (such as '10/31/96') or serial date numbers (such as 729329). If your array includes serial date numbers, convert these dates to their text representation using datestr before calling xlswrite.

• To write data to Excel files with custom formats (such as fonts or colors), access the Windows COM server directly using actxserver rather than xlswrite. For example, this MathWorks Support Answer uses actxserver to establish a connection between MATLAB and Excel, writes data to a worksheet, and specifies the colors of the cells.

Algorithms

Excel converts Inf values to 65535. MATLAB converts NaN values to empty cells.

Version History

Introduced before R2006a

R2019a: xlswrite is not recommended

xlswrite is not recommended. Use writetable, writematrix, or writecell instead. There are no plans to remove xlswrite.

Starting in R2019a, use writetable, writematrix, or writecell instead. The writetable, writematrix, and writecell functions have better cross-platform support and performance over the xlswrite function.

This table shows typical usages of xlswrite and how to update your code to use writetable, writematrix, or writecell instead.

Not Recommended	Recommended
xlswrite(filename,M)	To write tabular data to spreadsheets, use one of these options instead. Write a table: writetable(T,filename) Write a matrix: writematrix(M,filename) Write a cell array: writecell(C,filename)