MATLAB Function Reference

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 directory on the search path, above the directories supplied by The MathWorks™. The default directory is My Documents/MATLAB on Windows^® platforms, and Documents/MATLAB on Windows Vista™ platforms. On Apple^® Macintosh^® and The Open Group UNIX^® platforms, the default value is userhome/Documents/MATLAB. If you remove the userpath directory from the search path and save the changes to the path, it also has the effect of clearing the value of userpath. The userpath directory can also be the MATLAB^® startup directory. On Windows platforms, userpath is the startup directory, unless the startup directory is otherwise specified, such as by the MATLAB shortcut properties Start in field. On UNIX and Macintosh platforms, the startup directory is userpath if the value of the environment variable MATLAB_USE_USERPATH is set to 1 prior to startup and if the startup directory is not otherwise specified, such as via a startup.m file. On Macintosh platforms, you can use the Start MATLAB Settings dialog box to specify the startup directory, and when you start MATLAB from that dialog box or an icon created from it, userpath is added to the search path upon startup. On Macintosh and UNIX platforms, you can automatically add additional subdirectories to the top of the search path upon startup by specifying the path for the subdirectories via the MATLABPATH environment variable.

userpath('newpath') sets the userpath value to newpath. The newpath directory appears at the top of the search path immediately and upon the next startup. The directory previously specified by userpath is removed from the search path. newpath cannot be a relative path, and this does not work when the -nojvm startup option is used. Upon the next startup, newpath, can become the current directory, as described in the syntax for userpath with no arguments.

userpath('reset') sets the userpath value to the default for that platform, creating the .../MATLAB directory if it does not exist. The default directory is immediately added to the top of the search path, is also added to the path upon startup, and can become the startup directory as described for the userpath syntax with no arguments. The directory previously specified by userpath is removed from the search path. This does not work when the -nojvm startup option is used.

userpath('clear') clears the userpath value. The directory previously specified by userpath is removed from the search path. This does not work when the -nojvm startup option is used. The startup directory can be otherwise specified—see Startup Directory 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 run

cd

MATLAB displays the current directory

H:\My Documents\MATLAB

where H is the drive at which My Documents is located for this example. This is the directory specified by userpath. To confirm, run

userpath

and MATLAB returns

H:\My Documents\MATLAB;

Run

path

and MATLAB displays the search path; the userpath portion is at the top:

MATLABPATH

	H:\My Documents\MATLAB
	C:\Program Files\MATLAB\R2008a\toolbox\matlab\general
	C:\Program Files\MATLAB\R2008a\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. To change the value from the default for userpath to C:\Research_Project, run

userpath('C:\Research_Project')

To view the effect of the change on the search path, run

path

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

MATLABPATH

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

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

Clearing the Value for userpath, and Specifying a New Startup Directory on Windows^® Platforms

Assume userpath is set to the default value and you do not want any directories to be added to the search path upon startup. To confirm the default is currently set, run

userpath

and MATLAB returns

H:\My Documents\MATLAB

Note the userpath directory at the top of the search path by running

path

MATLAB returns

MATLABPATH

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

To clear the value, run

userpath('clear')

To verify the result, run

userpath

MATLAB returns

ans =
     ''

Confirm the userpath directory was removed from the path by running:

path

MATLAB returns

MATLABPATH

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

After clearing the userpath value, unless you otherwise specify the startup directory, it will be the desktop on Windows platforms. There are a number of ways to specify the startup directory. 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 directory in the Start in field, for example, I\:my_matlab_files\my_mfiles. The next time you start MATLAB, the current directory will be I\:my_matlab_files\my_mfiles, but that directory will not be on the search path. Note that you do not have to clear the userpath to specify a different startup directory; when you otherwise specify a startup directory, the userpath directory is added to the search path upon startup, but is not the startup directory.

Removing userpath from the Search Path; Resets the Startup Directory

In this example, assume userpath is set to the default value and you remove the userpath directory from the search path, then save the changes. This has the same effect as clearing the value for userpath. To confirm the default is currently set, run

userpath

and MATLAB returns

H:\My Documents\MATLAB

Note the userpath directory at the top of the search path by running

path

MATLAB returns

MATLABPATH

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

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

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

MATLAB returns

MATLABPATH

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

Running

userpath

at this point shows the value is still set

H:\My Documents\MATLAB

Save changes to the path by running

savepath

Now when you run

userpath

MATLAB returns

ans =
     ''

showing the value is now cleared. Removing the directory 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 directory will not be H:\My Documents\MATLAB, and H:\My Documents\MATLAB will not be on the search path.

Add userpath to Search Path Upon Startup, and Specify Different Startup Directory on Macintosh^® Platform

Open the Start MATLAB Settings dialog box. For Current directory, specify /Users/smith/Documents/MATLAB/my_files. Click Start MATLAB.

After MATLAB starts, run pwd to verify the current directory. MATLAB returns

/Users/smith/Documents/MATLAB/my_files

Verify the value for userpath by running

userpath

MATLAB returns

/Users/smith/Documents/MATLAB

Verify that userpath is at the top of the search path by running

path

MATLAB returns

/Users/smith/Documents/MATLAB
/Users/smith/Applications/MATLAB/R2008a/toolbox/matlab/general
/Users/smith/Applications/MATLAB/R2008a/toolbox/matlab/ops
...

Assigning userpath as the Startup Directory on a UNIX^® or Macintosh^® Platform

This example assumes userpath is set to the default value on a Macintosh platform and that 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 directory:

export MATLAB_USE_USERPATH=1

From that shell, start MATLAB. After MATLAB starts, verify its current directory by running

pwd

MATLAB returns

/Users/smith/Documents/MATLAB

That is the value defined for userpath, which you can confirm by running

userpath

MATLAB returns

/Users/smith/Documents/MATLAB

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

path

MATLAB returns

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

...

Adding Directories to the Search Path Upon Startup on a UNIX^® or Macintosh^® Platform

This example assumes 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 directories 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 directories 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/R2008a/toolbox/matlab/general
home/j/Applications/MATLAB/R2008a/toolbox/matlab/ops
...

userpath

Syntax

Description

Examples

Viewing userpath

Setting a New Value for userpath

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

Removing userpath from the Search Path; Resets the Startup Directory

Add userpath to Search Path Upon Startup, and Specify Different Startup Directory on Macintosh® Platform

Assigning userpath as the Startup Directory on a UNIX® or Macintosh® Platform

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

See Also

Clearing the Value for userpath, and Specifying a New Startup Directory on Windows^® Platforms

Add userpath to Search Path Upon Startup, and Specify Different Startup Directory on Macintosh^® Platform

Assigning userpath as the Startup Directory on a UNIX^® or Macintosh^® Platform

Adding Directories to the Search Path Upon Startup on a UNIX^® or Macintosh^® Platform