Learn more about MATLAB

Using the MATLAB Search Path

On this page…
What Is the Search Path? Viewing Files and Folders on the Search Path Changing the Search Path Using the Search Path with Different MATLAB Installations Recovering from Problems with the Search Path Handling Errors and Unexpected Behavior When Updating Folders

What Is the Search Path?

The search path, or path is a subset of all the folders in the file system. MATLAB software uses the search path to locate files used with MathWorks products efficiently. MATLAB can access all files in the folders on the search path.

What Is on the Search Path?

• By default, folders provided with MATLAB and other MathWorks products.

  These folders are under matlabroot/toolbox, where matlabroot is the folder displayed when you type matlabroot in the Command Window.

• By default, the MATLAB userpath. See Locations for Storing Your Files.

• Folders you explicitly add to the search path for the files you and others create.

  Adding folders to the search path is like performing an include or import operation in other applications.

Class, package, and private folders are not on the search path. See Files and Folders That MATLAB Can Access.

Order of Folders on the Search Path

The order of folders on the search path is important when two files with the same name are in folders on the search path. MATLAB uses the file nearest to the top of the search path. To customize the order of files on the search path, see Ensuring MATLAB Uses the File You Want.

Relationship Between the Search Path and the System Path

The search path is not the same as the system path. Furthermore, there is no explicit relationship between the MATLAB search path and the system path. However, both paths help in locating files, as follows:

• MATLAB uses the search path to locate MATLAB files efficiently.

• The operating system uses a system path to locate operating system files efficiently.

Therefore, you can issue MATLAB commands that result in the use of both the MATLAB search path and the system path. For example, if you type dos('tasklist &') in the MATLAB Command Window, then:

1. MATLAB uses the search path to locate and run dos.m.

2. The dos function passes 'tasklist &' to the Microsoft Windows operating system.

3. Microsoft Windows uses the system path to locate and run tasklist.exe.

Similar behavior results when you use the MATLAB unix and system functions or the shell escape (!). For details on using the shell escape with MATLAB, see Running External Programs.

How MATLAB Stores the Search Path

MATLAB saves the search path information in the pathdef.m file. The pathdef.m file is a series of full path names, one for each folder on the search path, separated by a semicolon (;).

By default, pathdef.m is in matlabroot/toolbox/local.

When you change the search path, MATLAB uses it in the current session. To use it in future sessions, save the changes as described in Saving Changes to the Search Path.

Back to Top

Viewing Files and Folders on the Search Path

MATLAB provides various ways for you to view the search path, as described in the following sections:

• Using the Current Folder Browser

• Using the Set Path Dialog Box

• Using MATLAB Search Path functions

Using the Current Folder Browser

To determine if files or folders in the Current Folder browser are on the search path:

1. Make sure Current Folder preferences are set to indicate files that are inaccessible to MATLAB.

   For details, see Controlling the Appearance of Files Inaccessible to MATLAB.

2. In the Current Folder browser, hover the pointer over any dimmed file to find out why it is dimmed.

   A tooltip opens with an explanation. Frequently, the tooltip indicates that the file is not on the MATLAB path. For example:

   

Using the Set Path Dialog Box

To view the entire MATLAB search path, select File > Set Path.

The Set Path dialog box opens, listing all folders on the search path.

Back to Top

Changing the Search Path

MATLAB provides various ways for you to change the search path, as described in the following sections:

• Adding Folders to the Search Path

• Removing Folders from the Search Path

• Changing the Order of Folders on the Search Path

• Saving Changes to the Search Path

• Specifying Startup Options Using the Startup File for the MATLAB Program, startup.m

• Using MATLAB Search Path functions

Adding Folders to the Search Path

You can add folders to the search path for the current session only, or for the current and future sessions.

Current Session Only.  To add folders to the search path for the duration of the current session:

1. Select and right-click the folder or folders to add.

2. From the context menu, select Add to Path, and then select an option:

   • Selected Folders

   • Selected Folders and Subfolders

MATLAB adds the specified folders to the top of the search path. If you do not want them at the top of the search path, see Changing the Order of Folders on the Search Path.

Current and Future Sessions.  To add folders to the search path for the current session and future sessions, use the addpath function, or follow these steps:

1. Open the Set Path dialog box by selecting File > Set Path.

2. Select an option:

   • Add Folder

   • Add with Subfolders

3. In the Browse For Folder dialog box, select the folder to add to the search path, and then click OK.

   MATLAB adds the specified folder to the top of the search path.

   If you do not want it at the top of the search path, see Changing the Order of Folders on the Search Path.

4. Keep or cancel the changes:

   • To use the newly modified search path only in the current session, click Close.

   • To reuse the newly modified search path in the current session and future sessions, click Save, and then click Close.

     For details on where to save the file, see Saving Changes to the Search Path.

   • To undo your changes, click Revert, and then click Close.

   • To restore the default search path, click Default, and then click Close. See Restoring the Default Search Path.

Removing Folders from the Search Path

You can remove folders from the search path for the current session only, or for the current and future sessions.

For the Current Session Only.  To remove folders to the search path for the duration of the current session:

1. Select and right-click the folder or folders to remove.

2. From the context menu, select Remove from Path, and then select an option:

   • Selected Folders

   • Selected Folders and Subfolders

For Current and Future Sessions.  To remove folders from the search path for the current and future sessions, use the rmpath function, or follow these steps:

1. Open the Set Path dialog box by selecting File > Set Path.

2. Select the folders to remove from the search path.

3. Click Remove.

4. Apply the changes:

   • To use the newly modified search path only in the current session, click Close.

   • To reuse the newly modified search path in the current session and future sessions, click Save.

     For details on where to save the file, see Saving Changes to the Search Path.

   • To restore the default search path, click Default. See Restoring the Default Search Path.

5. Click Close.

Changing the Order of Folders on the Search Path

Change the order of folders in the search path when files with the same name appear in multiple folders on the search path. When you specify such a file, MATLAB uses the one found in the folder nearest to the top of the search path.

Moving Folders to Various Positions on the Search Path.  To change the order of folders on the search path:

1. Open the Set Path dialog box by selecting File > Set Path.

2. Select the folders to remove from the search path.

3. Click one of the Move buttons, such as Move to Top. The order of the folders changes.

4. To use the modified search path in future sessions, click Save.

   If you do not save the changes, the newly modified search path remains in effect until you end the current MATLAB session.

5. Click Close.

Note   The MATLAB (userpath) folder automatically moves to the top of the search path the next time you start MATLAB. See Locations for Storing Your Files.

Moving a Folder to the Top or Bottom of the Search Path.  To move a folder to the top or bottom of the search path, use the path function.

Saving Changes to the Search Path

Changes you make to the search path always remain in effect during the current MATLAB session. For MATLAB to use the changed search path in future sessions, save the search path, which updates the pathdef.m file.

Note   The MATLAB (userpath) folder automatically moves to the top of the search path the next time you start MATLAB. See Locations for Storing Your Files.

Ways to Save Changes.  To save changes to the search path, do one of the following:

• Click Save in the Set Path dialog box. See Using the Set Path Dialog Box.

• Use the savepath function.

Where to Save the Search Path File.  Save the search path to the default location, matlabroot/toolbox/local, so MATLAB can locate it.

If you do not have write access to the default location, MATLAB prompts you for a different location. Choose the MATLAB startup folder.

Restoring the Default Search Path.  The default search path contains only folders provided by MathWorks.

To restore the default search path, do one of the following:

• Click Default in the Set Path dialog box. See Using the Set Path Dialog Box. This method also adds the userpath folder. See Locations for Storing Your Files.

• Use the restoredefaultpath function.

See also Recovering from Problems with the Search Path.

Back to Top

Using the Search Path with Different MATLAB Installations

Using the Search Path with Different Versions

The default search path changes for each MATLAB version because the default folders that come with the products change. Different MATLAB versions cannot use the same pathdef.m file.

To use your files with a new MATLAB version or with multiple versions, do one of the following:

• For each version, add the folders containing your files to the search path. Save the search path where that version of MATLAB can access it.

• Instead of changing the pathdef.m file, include addpath statements in the startup.m file. Use the same startup.m file with the multiple versions of MATLAB.

Using the Search Path with Different Platforms

To use your files with MATLAB on different platforms, include addpath statements in the startup.m file. For more information, see Specifying Startup Options Using the Startup File for the MATLAB Program, startup.m.

Back to Top

Recovering from Problems with the Search Path

When there is a problem with the search path, you cannot use MATLAB successfully.

You could experience search path problems when:

• You save the search path on a Windows platform, and then try to use the same pathdef.m file on a Linux platform.

• The pathdef.m file becomes corrupt, invalid, renamed, or deleted.

• MATLAB cannot locate the pathdef.m file.

For example, when you start MATLAB, if a message like the following appears, it indicates a problem with the search path:

Warning: MATLAB did not appear to successfully set the search 
path...

To recover from problems with the search path, try the following steps. Proceed from one step to the next only as necessary.

1. Ensure MATLAB is using the pathdef.m file you expect:

   1. Run

      which pathdef

   2. If you want MATLAB to use the pathdef.m file at another location, make corrections. For example, delete the incorrect pathdef.m file and ensure the correct pathdef.m file is in a location that MATLAB can access. See Where to Save the Search Path File.

2. Look for and correct problems with the pathdef.m and startup.m files:

   1. Open pathdef.m and startup.m in a text editor. Depending on the problem, you might not be able to open the pathdef.m file.

   2. Look for obvious problems, such as invalid characters or path names.

   3. Make corrections and save the files.

   4. Restart MATLAB to ensure that the problem does not recur.

3. Try to correct the problem using the Set Path dialog box:

   1. Restore the default search path and save it. See Using the Set Path Dialog Box. Depending on the problem, you might not be able to open the dialog box.

   2. Restart MATLAB to ensure that the problem does not recur.

4. Restore the default search path using functions:

   1. Run restoredefaultpath, which sets the search path to the default and stores it in matlabroot/toolbox/local.

   2. If restoredefaultpath seems to correct the problem, run savepath.

   3. Restart MATLAB to ensure that the problem does not recur.

   Depending on the problem, a message such as the following could appear:

   The path may be bad. Please save your work (if desired), and quit.

5. Correct the search path problems encountered during startup:

   1. Run

      restoredefaultpath; matlabrc

      Wait a few minutes until it completes.

   2. If there is a pathdef.m file in the startup folder, it caused the problem. Either remove the bad pathdef.m file or replace it with a good pathdef.m file. For example, run:

      savepath('path_to_your_startup_folder/pathdef.m')

      See Startup Folder for the MATLAB Program.

   3. Restart MATLAB to ensure that the problem does not recur.

After correcting problems with the search path, make any changes to run your files. For example, add the userpath folder or other folders to the search path.

Back to Top

Handling Errors and Unexpected Behavior When Updating Folders

You can encounter errors or unexpected behavior when you try to delete, rename, or move folders that:

• Are on the search path

• Contain subfolders that are on the search path

The behavior varies by platform because it depends on the behavior of similar features in the operating system.

If your task fails and the error message indicates it is because the folder is on the search path, then do one of the following:

• Remove the folder from the search path.

• Delete, rename, or move the folder.

• Add the folder to the search path.

Back to Top

Making Files and Folders Accessible to MATLAB

Related Topics for Managing Files

© 1984-2010- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS