RunMat
GitHub

View all functions

CategoryIo: Repl Fs

addpath — Add folders to the MATLAB search path used by RunMat.

addpath prepends or appends folders to the MATLAB search path that RunMat consults when resolving functions, scripts, classes, and data files. The change affects the current session immediately, and the resulting ordering matches MATLAB semantics.

How does the addpath function behave in MATLAB / RunMat?

  • Folder arguments may be character vectors, string scalars, string arrays, or cell arrays of character vectors or strings. Multi-row char arrays contribute one folder per row (trailing padding is stripped).
  • Multiple folders can be passed in a single argument using the platform path separator (: on Linux/macOS, ; on Windows); this is compatible with genpath.
  • By default, folders are added to the top of the search path. Use '-end' to append or '-begin' to force prepending explicitly. Only one position flag is permitted.
  • The '-frozen' flag is accepted for MATLAB compatibility. RunMat does not currently track frozen entries separately; the flag simply suppresses incompatibility warnings.
  • Duplicate entries are removed automatically so each folder appears at most once. On Windows, comparisons are case-insensitive.
  • Inputs are resolved to absolute, canonicalised paths. Relative inputs are interpreted relative to the current working directory, and ~ expands to the user’s home directory.
  • Folders must exist. RunMat raises addpath: folder '<name>' not found when a directory is missing or addpath: '<name>' is not a folder when the target is not a directory.

GPU behavior

addpath manipulates host-side configuration. If any input value resides on the GPU, RunMat gathers it back to the host before parsing. No acceleration provider hooks or kernels are involved.

GPU residency

No. addpath operates entirely on CPU-side strings. Supplying gpuArray text inputs offers no benefit—RunMat gathers them automatically.

Examples of using addpath in MATLAB / RunMat

Add a single folder to the top of the search path

mkdir("util/toolbox");
oldPath = path();
addpath("util/toolbox");
newPath = path();
count = fprintf('%s %s\n', oldPath, newPath);

Expected output:

/util/toolbox

Append folders to the end of the search path

mkdir("shared/filters");
mkdir("shared/signal");
oldPath = path();
dirs = ["shared/filters", "shared/signal"];
addpath(dirs, "-end");
newPath = path();
count = fprintf('%s %s\n', oldPath, newPath);

Expected output:

/shared/filters:/shared/signal

Use genpath output to add a folder tree

mkdir("third_party/toolchain");
mkdir("third_party/toolchain/bin");
oldPath = path();
toolchain = genpath("third_party/toolchain");
addpath(toolchain);
newPath = path();
count = fprintf('%s %s\n', oldPath, newPath);

Expected output:

/third_party/toolchain:/third_party/toolchain/bin

Add folders from a cell array

mkdir("src/algorithms");
mkdir("src/visualization");
oldPath = path();
folders = ["src/algorithms", "src/visualization"];
addpath(folders, "-begin");
newPath = path();
count = fprintf('%s %s\n', oldPath, newPath);

Expected output:

/src/algorithms:/src/visualization

Move an existing folder to the top of the search path

mkdir("src/algorithms");
oldPath = path();
addpath("src/algorithms");
newPath = path();
count = fprintf('%s %s\n', oldPath, newPath);

Expected output:

/src/algorithms

Accept the MATLAB -frozen flag

mkdir("vendor/hardware");
oldPath = path();
addpath("vendor/hardware", "-frozen");
newPath = path();
count = fprintf('%s %s\n', oldPath, newPath);

Expected output:

/vendor/hardware

Retrieve the previous path and restore it later

mkdir("analysis/utilities");
oldPath = path();
old = addpath("analysis/utilities");
newPath = path();
path(old);
count = fprintf('%s %s\n', oldPath, newPath);

Expected output:

/analysis/utilities

Combine multiple options

mkdir("contrib");
mkdir("docs/examples");
oldPath = path();
addpath("contrib", "docs/examples", "-end", "-frozen");
newPath = path();
count = fprintf('%s %s\n', oldPath, newPath);

Expected output:

/contrib:/docs/examples

FAQ

Does addpath insist on absolute paths?

No. Relative inputs are resolved against the current working directory and stored as absolute paths.

What happens with duplicate folders?

Existing occurrences are removed before the new ordering is applied, so each folder appears only once.

How do I append instead of prepend?

Supply '-end' as the final argument. Use '-begin' to force prepending explicitly.

Is -frozen supported?

The flag is accepted for MATLAB compatibility. RunMat currently treats it as a no-op but plans to integrate tighter tooling once savepath support lands.

Can I load pathdef.m directly?

Not yet. RunMat will add parity support in a future release. For now, evaluate the file manually and pass the resulting character vector to path.

Do folders need to exist?

Yes. RunMat validates that every entry exists and is a directory before updating the search path.

Will addpath accept GPU strings?

Yes. Inputs are gathered automatically, then processed on the CPU.

Does addpath return the new path?

Like MATLAB, addpath returns the previous path so it can be restored later with path(old).

See also

path, rmpath, genpath, which, exist

Source & Feedback