---

name: matlab-use-spreadsheet-link description: Exchange data between Excel and MATLAB using Spreadsheet Link VBA macros and worksheet functions. Use when writing Excel VBA macros that call MLPutMatrix, MLGetMatrix, MLPutVar, MLGetVar, MLPutRanges, MLEvalString, MLGetFigure, or MatlabRequest. license: https://www.mathworks.com/content/dam/mathworks/license/pmrl/license.md metadata: author: MathWorks version: "2.0"

Spreadsheet Link

Spreadsheet Link connects Excel to MATLAB, enabling users to exchange data between Excel and MATLAB, run MATLAB commands, using MATLAB as the compute engine from Excel.

When to Use

• User wants to export Excel data into MATLAB workspace variables
• User wants to import MATLAB variables back into Excel cells or VBA variables
• User wants to execute MATLAB commands from an Excel VBA macro or worksheet cell
• User wants to import MATLAB figures into Excel as images
• User is building a workflow that uses Excel as the data interface and MATLAB as the compute engine

When NOT to Use

• MATLAB-only workflows with no Excel involvement
• Python or .NET integration with MATLAB (use MATLAB Engine API instead)
• Deploying MATLAB as a web service (use MATLAB Production Server instead)

Architecture

Spreadsheet Link uses VBA macros or worksheet functions in Excel to communicate with a locally running MATLAB instance via COM.

┌─────────────────────┐         VBA / COM          ┌─────────────────────┐
│   Excel             │  ◄─────────────────────►   │  MATLAB             │
│   (VBA or cells)    │                            │  (workspace)        │
└─────────────────────┘                            └─────────────────────┘

• Windows only (requires MATLAB COM Server)
• MATLAB must be running locally
• Two usage modes: VBA macros or worksheet functions (cell formulas)
• Two data exchange styles: range-based (MLPutMatrix/MLGetMatrix) or VBA-variable-based (MLPutVar/MLGetVar)

Key Functions

| Function | Mode | Purpose | Queued? | |----------|------|---------|---------| | MLPutMatrix | Both | Export worksheet range to MATLAB variable | No | | MLPutVar | VBA only | Export VBA variable to MATLAB variable | No | | MLGetMatrix | Both | Import MATLAB variable to worksheet cells | Yes | | MLGetVar | VBA only | Import MATLAB variable into VBA variable | No | | MLPutRanges | Both | Export ALL named ranges to MATLAB | No | | MLEvalString | Both | Execute a MATLAB command | No | | MLGetFigure | Both | Import current MATLAB figure as image | Yes | | MatlabRequest | VBA only | Process all queued MLGetMatrix/MLGetFigure | — | | MLAppendMatrix | Both | Append worksheet range to existing MATLAB variable | No |

Function Reference

MLPutMatrix

Export an Excel range into MATLAB as a workspace variable.

VBA macro syntax:

MLPutMatrix "varName", Range("A1:B10")

Worksheet function syntax:

=MLPutMatrix("varName", A1:B10)

• First argument: MATLAB variable name (string)
• Second argument: Excel range containing the data
• Dates in Excel are sent as Excel serial date numbers

MLPutVar

Export a VBA variable to the MATLAB workspace. VBA only — not available as a worksheet function.

Dim myData As Variant
myData = Range("A1:B100").Value
MLPutVar "matlabVar", myData

• First argument: MATLAB variable name (string)
• Second argument: VBA variable (the variable itself, not a string name)
• Executes immediately (not queued)
• Use when data needs VBA manipulation before sending to MATLAB

MLGetMatrix

Queue a MATLAB variable to be written into Excel starting at a cell location.

MLGetMatrix "varName", "A1"

• First argument: MATLAB variable name (string)
• Second argument: destination cell address (string, not a Range object)
• Does NOT execute immediately — queued until MatlabRequest is called
• Supports all MATLAB data types; datetime values are converted to strings in Excel
• As worksheet function: =MLGetMatrix("varName", "E1")

MLGetVar

Import a MATLAB variable into a VBA variable. VBA only — not available as a worksheet function.

Dim result As Variant
MLGetVar "matlabVar", result

• First argument: MATLAB variable name (string)
• Second argument: VBA variable to receive the data
• Executes immediately — does NOT require MatlabRequest
• Supports all MATLAB data types; datetime values are converted to strings
• Use when results need VBA manipulation before writing to worksheet

MLPutRanges

Export ALL Excel named ranges to MATLAB in a single call. Each named range becomes a MATLAB variable with the same name.

MLPutRanges

• No arguments — exports every named range in the workbook
• Range name becomes the MATLAB variable name (e.g., named range "prices" → MATLAB variable prices)
• As worksheet function: =MLPutRanges()

MLEvalString

Execute a MATLAB command in the connected MATLAB session.

MLEvalString "x = magic(3);"

• Argument: MATLAB code as a string
• Executes synchronously — the next VBA line runs after MATLAB completes
• Can call any MATLAB function, script, or expression
• As worksheet function: =MLEvalString("x = magic(3);")

MLAppendMatrix

Append an Excel range to an existing MATLAB variable. The new data is concatenated as additional rows.

VBA macro syntax:

MLAppendMatrix "varName", Range("A101:B200")

Worksheet function syntax:

=MLAppendMatrix("varName", A101:B200)

• First argument: MATLAB variable name (string) — must already exist in workspace
• Second argument: Excel range to append
• Appends rows to the bottom of the existing variable
• Use when building up a variable incrementally (e.g., streaming data)

MLGetFigure

Import the current MATLAB figure into Excel as an image.

Range("I1").Select
MLGetFigure 1, 1

• Select the destination cell first with Range(...).Select
• First argument: horizontal size scaling factor (1 = full size, 0.5 = half width)
• Second argument: vertical size scaling factor (1 = full size, 0.5 = half height)
• Only two arguments — do NOT pass a cell address
• Retrieves whatever figure is currently active in MATLAB
• Queued until MatlabRequest is called (like MLGetMatrix)
• As worksheet function: =MLGetFigure(1, 1) — places figure at the formula cell

MatlabRequest

Process all pending MLGetMatrix and MLGetFigure commands and write results to Excel.

MatlabRequest

• Must be the last command in any VBA macro that uses MLGetMatrix or MLGetFigure
• Triggers the actual data transfer from MATLAB to Excel cells/images
• Without this call in a VBA macro, queued results will not appear in the spreadsheet
• NOT needed for MLGetVar (which executes immediately)
• Worksheet functions do NOT need explicit MatlabRequest — Spreadsheet Link's auto-calc functionality calls MatlabRequest automatically as part of Excel's recalculation cycle

Patterns

Pattern 1: VBA with MLPutVar/MLGetVar (preferred for VBA workflows)

Sub DataRoundTrip()
    ' Read data from worksheet into VBA variables
    Dim prices As Variant
    Dim weights As Variant
    prices = Range("A1:A100").Value
    weights = Range("B1:B100").Value

    ' Export VBA variables to MATLAB
    MLPutVar "prices", prices
    MLPutVar "weights", weights

    ' Compute in MATLAB
    MLEvalString "portfolio = prices .* weights;"
    MLEvalString "totalValue = sum(portfolio);"

    ' Import results into VBA variables (immediate — no MatlabRequest needed)
    Dim portfolio As Variant
    Dim totalValue As Variant
    MLGetVar "portfolio", portfolio
    MLGetVar "totalValue", totalValue

    ' Write VBA variables to worksheet
    Range("D1").Resize(UBound(portfolio, 1), UBound(portfolio, 2)).Value = portfolio
    Range("E1").Value = totalValue
End Sub

Pattern 2: VBA with MLPutMatrix/MLGetMatrix (range-based)

Sub ComputeInMatlab()
    MLPutMatrix "data", Range("A1:C100")
    MLEvalString "result = mean(data, 1);"
    MLGetMatrix "result", "E1"
    MatlabRequest
End Sub

Pattern 3: Named ranges export

Sub AnalyzeAllData()
    ' Export all named ranges to MATLAB at once
    ' e.g., "prices", "weights", "benchmark" all become MATLAB variables
    MLPutRanges

    ' MATLAB code references variables by named range names
    MLEvalString "portReturn = prices .* weights;"
    MLEvalString "excessReturn = portReturn - benchmark;"
    MLEvalString "sharpe = mean(excessReturn) / std(excessReturn) * sqrt(252);"

    ' Import result
    Dim sharpe As Variant
    MLGetVar "sharpe", sharpe
    Range("H1").Value = sharpe
End Sub

Pattern 4: Figure generation and import

Sub PlotAndImport()
    MLPutVar "data", Range("A1:B100").Value

    ' Generate MATLAB figure
    MLEvalString "figure;"
    MLEvalString "plot(data(:,1), data(:,2), 'LineWidth', 1.5);"
    MLEvalString "title('Analysis'); xlabel('X'); ylabel('Y'); grid on;"

    ' Import figure to Excel
    Range("D1").Select
    MLGetFigure 1, 1
    MatlabRequest
End Sub

Pattern 5: Multiple figures

Sub MultipleFigures()
    MLPutVar "data", Range("A1:C100").Value

    ' Create multiple figures
    MLEvalString "figure(1); plot(data(:,1)); title('Series 1');"
    MLEvalString "figure(2); histogram(data(:,2)); title('Distribution');"
    MLEvalString "figure(3); scatter(data(:,1), data(:,2)); title('Scatter');"

    ' Import each — must make figure current before each MLGetFigure
    MLEvalString "figure(1);"
    Range("E1").Select
    MLGetFigure 0.5, 0.5

    MLEvalString "figure(2);"
    Range("E20").Select
    MLGetFigure 0.5, 0.5

    MLEvalString "figure(3);"
    Range("E40").Select
    MLGetFigure 0.5, 0.5

    MatlabRequest
End Sub

Pattern 6: Complete workflow (MLPutVar + compute + MLGetVar + figure)

Sub TotalReturnWithFigure()
    ' Read data into VBA
    Dim prices As Variant
    Dim divs As Variant
    prices = Range("A1:B253").Value
    divs = Range("D1:E20").Value

    ' Export to MATLAB
    MLPutVar "prices", prices
    MLPutVar "divs", divs

    ' Compute total return
    MLEvalString "dates = datetime(prices(:,1), 'ConvertFrom', 'excel');"
    MLEvalString "px = prices(:,2);"
    MLEvalString "exDates = datetime(divs(:,1), 'ConvertFrom', 'excel');"
    MLEvalString "divAmounts = divs(:,2);"
    MLEvalString "adjFactor = ones(size(px));"
    MLEvalString "for i = 1:numel(exDates), idx = find(dates >= exDates(i), 1); if ~isempty(idx) && idx > 1, adjFactor(1:idx-1) = adjFactor(1:idx-1) * (1 - divAmounts(i)/px(idx)); end, end"
    MLEvalString "totalReturn = px ./ adjFactor;"
    MLEvalString "totalReturn = 100 * totalReturn / totalReturn(1);"

    ' Generate figure
    MLEvalString "figure;"
    MLEvalString "plot(dates, totalReturn, 'LineWidth', 1.5);"
    MLEvalString "title('Total Return Index');"
    MLEvalString "xlabel('Date'); ylabel('Index (Base = 100)'); grid on;"

    ' Import numeric result into VBA variable
    Dim trResult As Variant
    MLGetVar "totalReturn", trResult
    Range("G1").Resize(UBound(trResult, 1), 1).Value = trResult

    ' Import figure
    Range("I1").Select
    MLGetFigure 1, 1
    MatlabRequest
End Sub

Pattern 7: Worksheet functions (cell formulas)

Enter these in separate Excel cells, in order from top to bottom:

Cell F1: =MLPutRanges()
Cell F2: =MLEvalString("result = mean(prices, 1);")
Cell F3: =MLEvalString("figure; plot(prices); title('Prices'); grid on;")
Cell F4: =MLGetMatrix("result", "H1")
Cell F5: =MLGetFigure(1, 1)

Working with dates

Excel dates are sent as serial date numbers. Convert in MATLAB:

Dim rawData As Variant
rawData = Range("A1:B253").Value
MLPutVar "rawData", rawData
MLEvalString "dates = datetime(rawData(:,1), 'ConvertFrom', 'excel');"
MLEvalString "values = rawData(:,2);"

When to Use MLPutVar/MLGetVar vs MLPutMatrix/MLGetMatrix

Two parallel APIs exist for exchanging data between Excel and MATL