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.

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

Debug Using Run to Here

To explore the state of all variables in the workspace at a specific point in your code, run your code file and then pause. 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.

When debugging, the Run to Here button becomes the Continue to Here button . In functions and classes, running to a specified line and then pausing is only available when debugging using the Continue to Here button . In R2021a and previous releases, to run to where the cursor is positioned and pause while debugging, go to the Editor tab, and click the Run to Cursor button .

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.

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.

  

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 Continue to Here 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.

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.

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 or script that you want to step into. MATLAB displays the button only if the line contains a call to another function or script. 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 displays only for user-defined functions and scripts. To show the button for all functions and scripts, on the Home tab, in the Environment section, click Preferences. Then, select MATLAB > Editor/Debugger, and in the Debugging section, set the Show inline Step in buttons option to Always. To never show the button, set the Show inline Step in buttons option to Never.

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 Show inline Step in buttons 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.

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.

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.

  

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 disable 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.

Action	Description	Keyboard Shortcut	Function
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 at the current line, if no breakpoint exists.	F12	dbstop
Clear Breakpoint	Clear the breakpoint at the current line.	F12	dbclear

Related Topics

• Set Breakpoints
• Examine Values While Debugging
• Edit and Format Code

External Websites

• Programming: Structuring Code (MathWorks Teaching Resources)