userpath - View or change user portion of search path

Syntax

Description

userpath returns a string specifying the user portion of the search path. The user portion of the search path is the first folder on the search path, above the folders supplied by MathWorks. The default folder is Documents/MATLAB on all platforms except Windows platforms released before Windows Vista™—for those Windows platforms, the default is My Documents/MATLAB. By default, the userpath folder is the current folder when you start up MATLAB — that is, it is the default startup folder. For information on specifying a different folder for the startup folder, see Startup Folder for the MATLAB Program. On Macintosh and UNIX platforms, you can automatically add additional subfolders to the top of the search path upon startup by specifying the path for the subfolders via the MATLABPATH environment variable.

userpath('newpath') sets the userpath value to newpath. The newpath folder appears at the top of the search path immediately and at startup in future sessions. MATLAB removes the folder previously specified by userpath from the search path. newpath must be an absolute path.

userpath('reset') sets the userpath value to the default for that platform, creating the Documents/MATLAB (or My Documents/MATLAB) folder, if it does not exist. MATLAB immediately adds the default folder to the top of the search path, and also adds it to the search path at startup in future sessions.

userpath('clear') clears the value for userpath. MATLAB removes the folder previously specified by userpath from the search path.

Examples

• Viewing userpath

• Setting a New Value for userpath

• Clearing the Value for userpath, and Specifying a New Startup Folder on Windows Platforms

• Removing userpath from the Search Path Resets the Startup Folder

• Assigning userpath as the Startup Folder on a UNIX or Macintosh Platform

• Adding Folders to the Search Path Upon Startup on a UNIX or Macintosh Platform

Viewing userpath

This example assumes userpath is set to the default value on the Windows XP platform, My Documents\MATLAB. Start MATLAB and display the current folder:

cd

MATLAB returns:

H:\My Documents\MATLAB

where H is the drive at which My Documents is located for this example. Confirm the current folder is the userpath:

userpath

MATLAB returns:

H:\My Documents\MATLAB;

Display the search path:

path

MATLAB returns the search path. The userpath portion is at the top:

MATLABPATH

	H:\My Documents\MATLAB
	C:\Program Files\MATLAB\R2009a\toolbox\matlab\general
	C:\Program Files\MATLAB\R2009a\toolbox\matlab\ops

Setting a New Value for userpath

This example assumes userpath is set to the default value on the Windows XP platform, My Documents\MATLAB. Change the value from the default for userpath to C:\Research_Project:

userpath('C:\Research_Project')

View the effect of the change on the search path:

path

MATLAB displays the search path, with the new value for userpath portion at the top:

MATLABPATH

	C:\Research_Project
	C:\Program Files\MATLAB\R2009a\toolbox\matlab\general
	C:\Program Files\MATLAB\R2009a\toolbox\matlab\ops
...

Note that MATLAB automatically removed the previous value of userpath, H:\My Documents\MATLAB, from the search path when you assigned a new value to userpath. The next time you start MATLAB, the current folder will be C:\Research_Project on Windows platforms.

Clearing the Value for userpath, and Specifying a New Startup Folder on Windows Platforms

Assume userpath is set to the default value and you do not want any folders to be added to the search path upon startup. Confirm the default is currently set:

userpath

MATLAB returns:

H:\My Documents\MATLAB;

Verify that the userpath folder is at the top of the search path:

path

MATLAB returns:

MATLABPATH

H:\My Documents\MATLAB
C:\Program Files\MATLAB\R2009a\toolbox\matlab\general
C:\Program Files\MATLAB\R2009a\toolbox\matlab\ops
...

Clear the value:

userpath('clear')

Verify the result:

userpath

MATLAB returns:

ans =
     ''

Confirm the userpath folder was removed from the search path:

path

MATLAB returns

MATLABPATH

C:\Program Files\MATLAB\R2009a\toolbox\matlab\general
C:\Program Files\MATLAB\R2009a\toolbox\matlab\ops
...

Clearing the userpath value might affect the startup folder. Unless you otherwise specify the startup folder, the startup folder on Windows platforms will be the folder from which you invoke MATLAB. If you specify a startup folder, such as described in Changing the Startup Folder, that startup folder will not be on the search path. Note that you do not have to clear userpath to specify a different startup folder; when you otherwise specify a startup folder, the userpath folder is added to the search path upon startup, but is not the startup folder.

Removing userpath from the Search Path Resets the Startup Folder

In this example, userpath is set to the default value and you remove the userpath folder from the search path, then save the changes. This has the same effect as clearing the value for userpath. Confirm the default is currently set:

userpath

MATLAB returns:

H:\My Documents\MATLAB;

View the userpath folder at the top of the search path:

path

MATLAB returns:

MATLABPATH

H:\My Documents\MATLAB
C:\Program Files\MATLAB\R2009a\toolbox\matlab\general
C:\Program Files\MATLAB\R2009a\toolbox\matlab\ops
...

Remove H:\My Documents\MATLAB from the search path and confirm the result:

rmpath('H:\My Documents\MATLAB')
path

MATLAB returns:

MATLABPATH

	C:\Program Files\MATLAB\R2009a\toolbox\matlab\general
	C:\Program Files\MATLAB\R2009a\toolbox\matlab\ops
...

Verify the value:

userpath

MATLAB returns:

H:\My Documents\MATLAB;

Save changes to the search path:

savepath

View the value:

userpath

MATLAB returns:

ans =
     ''

The value is now cleared. Removing the folder from the search path and saving the changes to the path has the same effect as clearing the value for userpath. At the next startup, the startup folder will not be H:\My Documents\MATLAB, and H:\My Documents\MATLAB will not be on the search path.

Assigning userpath as the Startup Folder on a UNIX or Macintosh Platform

Assume userpath is set to the default value on a Macintosh platform and you start MATLAB using a bash X11 shell, where smith is the home folder. Set the MATLAB_USE_USERPATH environment variable so that userpath will be used as the startup folder:

export MATLAB_USE_USERPATH=1

From that shell, start MATLAB. After MATLAB starts, verify the current folder in MATLAB:

pwd

MATLAB returns:

/Users/smith/Documents/MATLAB

That is the folder defined for userpath, which you can confirm:

userpath

MATLAB returns:

/Users/smith/Documents/MATLAB;

The userpath is at the top of the search path, which you can confirm:

path

MATLAB returns:

/Users/smith/Documents/MATLAB
/Users/smith/Applications/MATLAB/R2009a/toolbox/matlab/general
/Users/smith/Applications/MATLAB/R2009a/toolbox/matlab/ops

...

Adding Folders to the Search Path Upon Startup on a UNIX or Macintosh Platform

Assume userpath is set to the default value on a UNIX platform with a csh shell, where j is your home folder.

To add additional folders to the search path upon startup, for example, /home/j/Documents/MATLAB/mine and /home/j/Documents/MATLAB/mine/research, run the following in an X11 terminal:

setenv MATLABPATH '/home/j/Documents/MATLAB/mine':'/home/j/Documents/MATLAB/mine/research'

Separate multiple folders using a colon (:).

MATLAB displays

MATLABPATH

home/j/Documents/MATLAB
home/j/Documents/MATLAB/mine
home/j/Documents/MATLAB/mine/research
home/j/Applications/MATLAB/R2009a/toolbox/matlab/general
home/j/Applications/MATLAB/R2009a/toolbox/matlab/ops
...

See Also

addpath | path | pathtool | rmpath | savepath | startup

How To

• Using the MATLAB Search Path
• Startup Folder for the MATLAB Program