run — Execute a MATLAB script file in the caller workspace.
run locates a .m script by file name, relative path, absolute path, or active MATLAB search path entry, then executes that script in the caller workspace. Variables assigned by the script are visible to following statements in the caller.
Syntax
run(script)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
script | StringScalar | Yes | — | Script name or path to execute in the caller workspace. |
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:run:RequiresVm | `run` is dispatched outside an active VM workspace frame. | run: requires VM workspace context |
RunMat:run:InvalidScriptArgument | The script argument is not a character row, string scalar, or scalar string array. | run: script must be a character vector or string scalar |
RunMat:run:EmptyScript | The script argument is an empty path. | run: script path must not be empty |
RunMat:run:PathResolveFailed | RunMat cannot resolve the current directory, home directory, or search path. | run: failed to resolve script path |
RunMat:run:FileNotFound | No matching script file exists in the current directory or RunMat search path. | run: script file not found |
RunMat:run:FileReadFailed | The matched script file cannot be read as source text. | run: failed to read script file |
RunMat:run:TooManyOutputs | `run` is called with one or more requested output arguments. | run: too many output arguments |
How run works
run('script')resolvesscript.mwhen no extension is supplied. Bare.mfilenames also search the active MATLAB path.run('folder/script.m')executes the file at that path.- Command syntax is supported:
run script_nameis equivalent torun('script_name'). - The target file is executed as a script, not as a function. Assignments mutate the caller workspace and local functions in the script remain available to that script.
mfilenameinside the executed script reports the executed file name and full path, matching the script source context.runhas no outputs. Requesting an output raisesRunMat:run:TooManyOutputsbefore executing the file.- If the script throws an error, the error is catchable by the caller and assignments performed before that error remain in the caller workspace.
- Names that may be introduced by a script are tracked as dynamic workspace bindings. Bare reads of names the script did not assign raise
RunMat:UndefinedVariableat runtime unless the name is a builtin constant; call syntax such asname(...)checks the caller workspace first, then falls back to normal function or builtin resolution.
Does RunMat run run on the GPU?
run is a host-side script execution boundary. It does not create GPU kernels or participate in fusion. Values created by the executed script can still be promoted by downstream acceleration heuristics.
GPU memory and residency
No manual action is required. run always executes on the host. Any GPU-resident text argument is gathered before path resolution.
Examples
Execute a script in the current folder
run('setup_experiment');
result = configured_gain * 2;Execute a script found on the search path
addpath('examples');
run fm_demo
plot(t, demodulated)Catch script execution errors
try
run('maybe_missing_script');
catch e
disp(e.identifier)
endUsing run with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how run changes the result.
Run a small run example, explain the result, then change one input and compare the output.
FAQ
Does run call functions?⌄
No. run executes script files. Function files should be called by their function name.
Can run return a value?⌄
No. MATLAB's run executes for side effects in the caller workspace and does not return outputs.
Where does run search?⌄
RunMat first resolves the provided file or relative path, then searches the active MATLAB path. It appends .m when the supplied name has no extension, and a bare filename that already ends in .m is also searched on the active path.
What happens if the script creates variables?⌄
Assignments made by the script are visible in the caller workspace after run. Subsequent call syntax uses MATLAB variable precedence, so a script-created array can be indexed with x(...) and can shadow a builtin name.
What happens if the script fails?⌄
The error propagates to the caller and can be caught with try/catch. Assignments made before the error remain visible in the caller workspace, matching script execution semantics.
Related Io functions
Repl Fs
addpath · cd · copyfile · delete · dir · exist · fullfile · genpath · getenv · ls · mkdir · movefile · path · pwd · rmdir · rmpath · savepath · setenv · tempdir · tempname
Tabular
csvread · csvwrite · dlmread · dlmwrite · readmatrix · writematrix
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite
Json
Http
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how run is executed, line by line, in Rust.
- View the source for run 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.