savepath — Write the current MATLAB search path to pathdef.m with MATLAB-compatible status diagnostics.
savepath writes the current MATLAB search path to a pathdef.m file so future sessions can restore the same ordering. It follows MATLAB-compatible return codes and diagnostic messages for success and failure paths.
Syntax
status = savepath()
status = savepath(filename)
[status, message, message_id] = savepath()
[status, message, message_id] = savepath(filename)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
filename | StringScalar | Yes | "pathdef.m" | Target file or target directory for persisted pathdef output. |
Returns
| Name | Type | Description |
|---|---|---|
status | NumericScalar | 0 on success, 1 on failure. |
message | StringScalar | Failure message text, or empty on success. |
message_id | StringScalar | Failure identifier, or empty on success. |
Returned values from savepath depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
| — | Filename input is not a character vector, string scalar/array scalar, or tensor of character codes. | savepath: filename must be a character vector or string scalar |
| — | Explicit filename argument is empty. | savepath: filename must not be empty |
| — | More than one positional input argument is provided. | savepath: too many input arguments |
RunMat:savepath:cannotWriteFile | Pathdef file could not be written. | savepath: unable to write file |
RunMat:savepath:cannotResolveFile | Pathdef output path could not be resolved. | savepath: unable to resolve output path |
How savepath works
savepath()with no inputs writes to the default RunMat location ($HOME/.runmat/pathdef.mon Linux/macOS,%USERPROFILE%\.runmat\pathdef.mon Windows). The directory is created automatically when required.savepath(file)writes to the specified file. Relative paths are resolved against the current working directory,~expands to the user's home folder, and supplying a directory (with or without a trailing separator) appends the standardpathdef.mfilename automatically.- The function does not modify the in-memory search path - it only writes the current state to disk. Callers can therefore continue editing the path after saving without interference.
status = savepath(...)returns0on success and1when the file cannot be written.[status, message, messageID] = savepath(...)returns MATLAB-style diagnostics describing the failure. Both message outputs are empty on success.- Invalid argument types raise
savepath: filename must be a character vector or string scalar. Empty filenames raisesavepath: filename must not be empty. - When the
RUNMAT_PATHDEFenvironment variable is set, the zero-argument form uses that override instead of the default location.
Does RunMat run savepath on the GPU?
savepath runs entirely on the host. If callers supply a GPU-resident string, RunMat gathers it back to CPU memory before resolving the target path. No acceleration provider hooks or kernels are required.
GPU memory and residency
No. Because savepath interacts with the filesystem, GPU residency provides no benefit. The builtin automatically gathers GPU text inputs so existing scripts continue to work even if they accidentally construct filenames on the device.
Examples
Save The Current Search Path To The Default Location
status = savepath()Expected output:
status =
0Persist A Project-Specific Pathdef File
status = savepath("config/project_pathdef.m")Expected output:
status =
0Capture Status, Message, And Message ID
[status, message, messageID] = savepath("config/pathdef.m");
if status ~= 0
warning("Failed to save the path: %s (%s)", message, messageID);
endAppend Genpath Output And Persist The Result
tooling = genpath("third_party/toolchain");
addpath(tooling, "-end");
savepath()Save A Pathdef Using A Directory Argument
mkdir("~/.runmat/projectA");
savepath("~/.runmat/projectA/")Expected output:
% Creates ~/.runmat/projectA/pathdef.m with the current search path.Saving the path to a configured target
setenv("RUNMAT_PATHDEF", fullfile(tempdir, "pathdef-dev.m"));
savepath()Expected output:
% The file tempdir/pathdef-dev.m now contains the MATLAB path definition.Use gpuArray Inputs Transparently
status = savepath(gpuArray("pathdefs/pathdef_gpu.m"))Expected output:
status =
0Inspect The Generated pathdef.m File
savepath("toolbox/pathdef.m");
type toolbox/pathdef.mExpected output:
% Displays the MATLAB function that reproduces the saved search path.Using savepath with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how savepath changes the result.
Run a small savepath example, explain the result, then change one input and compare the output.
FAQ
Where does savepath write by default?⌄
RunMat uses $HOME/.runmat/pathdef.m (Linux/macOS) or %USERPROFILE%\.runmat\pathdef.m (Windows). Set RUNMAT_PATHDEF to override this location.
Does savepath create missing folders?⌄
Yes. When the parent directory does not exist, RunMat creates it automatically before writing the file.
What happens if the file is read-only?⌄
savepath returns status = 1 together with the diagnostic message and message ID RunMat:savepath:cannotWriteFile. The existing file is left untouched.
Does savepath modify the current path?⌄
No. It only writes out the path. Use addpath, rmpath, or path to change the in-memory value.
Are argument types validated?⌄
Yes. Inputs must be character vectors or string scalars. String arrays with multiple elements and numeric arrays raise an error.
Is the generated file MATLAB-compatible?⌄
Yes. RunMat writes a MATLAB function named pathdef that returns the exact character vector stored by the path builtin, so MathWorks MATLAB and RunMat can both execute it.
How do I restore the path later?⌄
Evaluate the generated pathdef.m (for example by calling run('~/pathdef.m')) and pass the returned value to path(). Future RunMat releases will load the default file automatically.
Can I store multiple path definitions?⌄
Absolutely. Call savepath with different filenames for each profile, then run the desired file to switch.
Is savepath safe to call concurrently?⌄
The builtin serializes through the filesystem. When multiple sessions write to the same path at once, the last write wins - this matches MATLAB's behavior.
Does savepath include the current folder (pwd)?⌄
The file mirrors the output of the path builtin, which omits the implicit current folder exactly as MATLAB does.
Related Io functions
Repl Fs
addpath · cd · copyfile · delete · dir · exist · fileattrib · fileparts · fullfile · genpath · getenv · getpref · isenv · isfile · isfolder · ispref · ls · matlabroot · memmapfile · mkdir · movefile · open · opentoline · path · pathsep · pcode · pwd · readstruct · rehash · restoredefaultpath · rmdir · rmpath · run · setenv · setpref · system · tempdir · tempname · uigetdir · uigetfile · uiputfile · unsetenv · userpath · what · winqueryreg · xmlread · xmlwrite
Tabular
arrayDatastore · csvread · csvwrite · detectImportOptions · dlmread · dlmwrite · fileDatastore · parquetDatastore · parquetinfo · parquetread · readcell · readmatrix · readtable · readtimetable · spreadsheetImportOptions · writecell · writematrix · writetable · writetimetable · xlsread · xlswrite
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite · readlines · writelines
Import
Json
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how savepath is executed, line by line, in Rust.
- View the source for savepath in Rust on GitHub
- Learn how the RunMat runtime works
- Found a bug? Open an issue with a minimal reproduction.
About RunMat
RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.
- RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
- Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.