Products & Services Industries Academia Support User Community Company

Learn more about MATLAB   

userpath - View or change user portion of search path

Syntax

userpath
userpath('newpath')
userpath('reset')
userpath('clear')

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 The MathWorks. The default folder is My Documents/MATLAB on Microsoft Windows platforms, and Documents/MATLAB on Microsoft Windows Vista™ platforms. On Apple Macintosh and UNIX[1] platforms, the default value is userhome/Documents/MATLAB. You can define the userpath folder to also be the MATLAB startup folder. On Windows platforms, userpath is the startup folder, unless the startup folder is otherwise specified, such as by the MATLAB shortcut properties Start in field. On UNIX and Macintosh platforms, the startup folder is userpath if the value of the environment variable MATLAB_USE_USERPATH is set to 1 prior to startup and if the startup folder is not otherwise specified, such as via a startup.m file. 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('newpath') does not work when the -nojvm startup option is used. Upon the next startup, newpath, can become the current folder, as described in the syntax for userpath with no arguments.

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. It can become the startup folder as described for the userpath syntax with no arguments. MATLAB removes the folder previously specified by userpath from the search path. userpath('reset') does not work when the -nojvm startup option is used.

userpath('clear') clears the value for userpath. MATLAB removes the folder previously specified by userpath from the search path. This does not work when the -nojvm startup option is used. You can otherwise specify the startup folder—see Startup Folder for the MATLAB Program.

Examples

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

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

After clearing the userpath value, unless you otherwise specify the startup folder, the startup folder will be the desktop on Windows platforms. There are a number of ways to specify the startup folder. For example, right-click the Windows shortcut icon for MATLAB and select Properties from the context menu. In the Properties dialog box Shortcut tab, enter the full path to the new startup folder in the Start in field, for example, I\:my_matlab_files\my_mfiles. The next time you start MATLAB, the current folder will be I\:my_matlab_files\my_mfiles, but that 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

See 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

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 directory. 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 value 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

userpath is set to the default value on a UNIX platform with a csh shell, where j is the user's home directory.

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,

Topics in the User Guide:

[1] UNIX is a registered trademark of The Open Group in the United States and other countries.

  

usejavausejava validateattributesvalidateattributes

Recommended Products

Get MATLAB trial software

Includes the most popular MATLAB recorded presentations with Q&A sessions led by MATLAB experts.

Get the Interactive Kit

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