Main Content

Debug MATLAB Code Files

Since R2021b. Replaces Debug a MATLAB Program (R2021a) and Debug Code in the Live Editor (R2021a).

You can diagnose problems in your MATLAB® code files by debugging your code interactively in the Editor and Live Editor or programmatically by using debugging functions in the Command Window.

There are several ways to debug your code:

  • Display output by removing semicolons.

  • Run the code to a specific line and pause by clicking the Run to Here button.

  • Step into functions and scripts while paused by clicking the Step In button.

  • Add breakpoints to your file to enable pausing at specific lines when you run your code.

Before you begin debugging, to avoid unexpected results, save your code files and make sure that the code files and any files they call exist on the search path or in the current folder. MATLAB handles unsaved changes differently depending on where you are debugging from:

  • Editor — If a file contains unsaved changes, MATLAB saves the file before running it.

  • Live Editor — MATLAB runs all changes in a file, whether they are saved or not.

  • Command Window — If a file contains unsaved changes, MATLAB runs the saved version of the file. You do not see the results of your changes.

Display Output

One way to determine where a problem occurs in your MATLAB code file is to display the output. To display the output for a line, remove the semicolon from the end of that line. In the Editor, MATLAB displays the output in the Command Window. In the Live Editor, MATLAB displays the output with the line of code that creates it.

For example, suppose that you have a script called plotRand.m that plots a vector of random data and draws a horizontal line on the plot at the mean.

n = 50;
r = rand(n,1);
plot(r)

m = mean(r);
hold on
plot([0,n],[m,m])
hold off
title('Mean of Random Uniform Data')

To display the output of the rand function at line two, remove the semicolon at the end of the line. MATLAB displays the value of r in the Command Window.

Command window showing a call to the plotRand function followed by the resulting output, the value of r

In the Live Editor, MATLAB displays the value of r with line two.

plotRand live script with the semicolon removed from the end of line two and the resulting output, the value of r, displayed on the right

Debug by Using Run to Here Button

If you want to display the state of a single variable, displaying output is useful. To explore the state of all variables in the workspace, run your code file, and then pause before running the specified line of code.

To run code to a specified line, and then pause, click the Run to Here button to the left of the line. If the selected line cannot be reached, MATLAB continues running until the end of the file is reached or a breakpoint is encountered.

Note

In functions and classes, the Run to Here button is available only when debugging.

For example, click the Run to Here button to the left of line two in plotRand.m. MATLAB runs plotRand.m starting at line one and pauses before running line two.

plotRand script with the Run to Here button displayed in the left margin, next to the line number for line two

When MATLAB pauses, multiple changes occur:

  • The Run button in the Editor or Live Editor tab changes to a Continue button.

  • The prompt in the Command Window changes to K>> indicating that MATLAB is in debug mode and that the keyboard is in control.

  • MATLAB indicates the line at which it is paused by using a green arrow and green highlighting.

    plotRand script with a green arrow and green highlighting on line two, indicating that MATLAB is paused at line two

Tip

It is a good practice to avoid modifying a file while MATLAB is paused. Changes that are made while MATLAB is paused do not run until after MATLAB finishes running the code and the code is rerun.

The line at which MATLAB is paused does not run until after you continue running the code. To continue running the code, click the Continue button. MATLAB continues running the file until it reaches the end of the file or a breakpoint. You also can click the button to the left of the line of code that you want to continue running to.

To continue running the code line-by-line, on the Editor or Live Editor tab, click Step. MATLAB executes the current line at which it is paused and the pauses at the next line.

plotRand script with a green arrow and green highlighting on line three, indicating that MATLAB is paused at line three

View Variable Value While Debugging

To view the value of a variable while MATLAB is paused, place your cursor over the variable. The current value of the variable appears in a data tip. The data tip stays in view until you move the cursor. To disable data tips, go to the View tab and click the Datatips button off.

plotRand script paused at line two with a data tip showing the value of the variable n

You also can view the value of a variable by typing the variable name in the Command Window. For example, to see the value of the variable n, type n and press Enter. The Command Window displays the variable name and its value. To view all the variables in the current workspace, use the Workspace browser.

For more information, see Examine Values While Debugging.

Pause a Running File

You can pause long running code while it is running to check on the progress and ensure that it is running as expected. To pause running code, go to the Editor or Live Editor tab and click the Pause button. MATLAB pauses at the next executable line, and the Pause button changes to a Continue button. To continue running the code, press the Continue button.

Note

Clicking the Pause button can cause MATLAB to pause in a file outside your own code.

Step Into Functions

While debugging, you can step into called files, pausing at points where you want to examine values. To step into a file, click the Step In button directly to the left of the function that you want to step into. MATLAB displays the button only if the line contains a call to another function. After stepping in, click the Step Out button at the top of the file to run the rest of the called function, leave the called function, and then pause.

By default, the Step In button is available only for user-defined functions and scripts. To make the button active for MathWorks® functions, on the Home tab, in the Environment section, click Preferences. Then, select MATLAB > Editor/Debugger, and in the Debugging section, clear the Only show contextual Step in button for user-defined functions option.

Alternatively, you can step in and out of functions while debugging by using the Step In or Step Out buttons on the Editor or Live Editor tab. These buttons do not honor the Only show contextual Step in button for user-defined functions preference and always step in and out of user-defined and MathWorks functions.

Function Call Stack

When you step into a called function or file, MATLAB displays the list of the functions it executed before pausing at the current line. The list, also called the function call stack, is shown at the top of the file and displays the functions in order, starting on the left with the first called script or function, and ending on the right with the current script or function in which MATLAB is paused.

Function call stack for plotRand showing plotRand as the first called script and mean as the current function

For each function in the function call stack, there is a corresponding workspace. Workspaces contain variables that you create within MATLAB or import from data files or other programs. Variables that you assign through the Command Window or create by using scripts belong to the base workspace. Variables that you create in a function belong to their own function workspace.

You can examine the values of variables outside of the current workspace by selecting a different workspace. For more information, see Examine Values While Debugging.

Add Breakpoints and Run Code

If there are lines of code in your file that you want to pause at every time you run your code, add breakpoints at those lines. You can add breakpoints interactively by using the Editor and Live Editor, programmatically by using functions in the Command Window, or both.

There are three types of breakpoints: standard, conditional, and error. To add a standard breakpoint in the Editor or Live Editor, click the gray area to the left of the executable line where you want to set the breakpoint. For example, click the area next to line three in plotRand.m to add a breakpoint at that line.

plotRand script with a red breakpoint at line three

When you run the file, MATLAB pauses at the line of code indicated by the breakpoint. The line at which MATLAB is paused does not run until after you continue running your code.

For example, with the plotRand.m file open in the Editor, click the Run button in the Editor tab. MATLAB runs plotRand.m starting at line one and pauses before running line three.

When MATLAB pauses, multiple changes occur:

  • The Run button in the Editor or Live Editor tab changes to a Continue button.

  • The prompt in the Command Window changes to K>> indicating that MATLAB is in debug mode and that the keyboard is in control.

  • MATLAB indicates the line at which it is paused by using a green arrow and green highlighting.

    plotRand script with a breakpoint at line three and a green arrow and green highlighting on line three, indicating that MATLAB is paused at line three

Tip

It is a good practice to avoid modifying a file while MATLAB is paused. Changes that are made while MATLAB is paused do not run until after MATLAB finished running the code and the code is rerun.

To continue running the code, click the Continue button. MATLAB continues running the file until it reaches the end of the file or a breakpoint. To continue running the code line-by-line, on the Editor or Live Editor tab, click Step. MATLAB executes the current line at which it is paused, and then pauses at the next line.

For more information about the different types of breakpoints and how to set, clear, and disabled them, see Set Breakpoints.

End Debugging Session

After you identify a problem, to end the debugging session, go to the Editor or Live Editor tab and click Stop. After you end debugging, the normal >> prompt in the Command Window reappears in place of the K>> prompt. You no longer can access the function call stack.

To avoid confusion, make sure to end your debugging session every time you are done debugging. If you make changes to a file and save it while debugging, MATLAB ends the debugging session. If MATLAB becomes unresponsive when it pauses, press Ctrl+C to end debugging.

Debug by Using Keyboard Shortcuts or Functions

You can perform most debugging actions by using keyboard shortcuts or by using functions in the Command Window. This table describes debugging actions and the related keyboard shortcuts and functions that you can use to perform them.

ActionDescriptionKeyboard ShortcutFunction

Continue

Continue running file until the end of the file is reached or until another breakpoint is encountered.

F5

dbcont

Step

Run the current line of code.

F10

(Shift+Command+O on macOS systems)

dbstep

Step In

Run the current line of code, and, if the line contains a call to another function, step into that function.

F11

(Shift+Command+I on macOS systems)

dbstep in

Step Out

After stepping in, run the rest of the called function, leave the called function, and then pause.

Shift+F11

(Shift+Command+U on macOS systems)

dbstep out

Stop

End debugging session.

Shift+F5

dbquit

Set Breakpoint

Set a breakpoint a the current line, if no breakpoint exists.

F12

dbstop

Clear Breakpoint

Clear the breakpoint at the current line.

F12

dbclear

Related Topics