`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.m on Linux/macOS, %USERPROFILE%\.runmat\pathdef.m on 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 standard pathdef.m filename 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(...) returns 0 on success and 1 when 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 raise savepath: filename must not be empty.
When the RUNMAT_PATHDEF environment 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 =
     0

Persist A Project-Specific Pathdef File

status = savepath("config/project_pathdef.m")

Expected output:

status =
     0

Capture 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);
end

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

Override The Target File With RUNMAT_PATHDEF

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 =
     0

Inspect The Generated pathdef.m File

savepath("toolbox/pathdef.m");
type toolbox/pathdef.m

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

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.

Getting started · Benchmarks · Pricing

savepath — Write the current MATLAB search path to pathdef.m with MATLAB-compatible status diagnostics.

Syntax

Inputs

Returns

Errors

How savepath works

Does RunMat run savepath on the GPU?

GPU memory and residency

Examples

Save The Current Search Path To The Default Location

Persist A Project-Specific Pathdef File

Capture Status, Message, And Message ID

Append Genpath Output And Persist The Result

Save A Pathdef Using A Directory Argument

Override The Target File With RUNMAT_PATHDEF

Use gpuArray Inputs Transparently

Inspect The Generated pathdef.m File

Using savepath with coding agents

FAQ

Related Io functions

Repl Fs

Net

Io

Tabular

Filetext

Json

Mat

Http

Open-source implementation

About RunMat

Download RunMat

`savepath` — Write the current MATLAB search path to `pathdef.m` with MATLAB-compatible status diagnostics.

How `savepath` works

Does RunMat run `savepath` on the GPU?

Using `savepath` with coding agents