setenv — Set or clear environment variables with MATLAB-compatible status outputs.

setenv updates the process environment. Provide a variable name and value to create or modify an entry, or pass an empty value to remove the variable. The builtin mirrors MATLAB by returning a status code and optional diagnostic message instead of throwing for platform-defined failures.

How setenv works in RunMat

• status = setenv(name, value) returns 0 when the update succeeds and 1 when the operating system rejects the request. The status output is a double scalar, matching MATLAB.
• [status, message] = setenv(name, value) returns the status plus a character vector describing failures. On success, message is an empty 1×0 character array.
• Set value to an empty string ("") or empty character vector ('') to remove the variable from the current process environment.
• Names must be string scalars or character vectors containing only valid environment variable characters. MATLAB raises an error when name is not text; RunMat mirrors this check.
• Character vector inputs trim trailing padding spaces (common with MATLAB character matrices). To retain trailing spaces, pass a string scalar instead.
• Environment updates apply to the RunMat process and any child processes it spawns. They do not modify the parent shell.

How setenv runs on the GPU

setenv always runs on the CPU. If a caller stores the arguments on the GPU—for instance via an accelerated string builtin—RunMat gathers them to host memory automatically before mutating the environment. Acceleration providers do not implement hooks for this builtin.

GPU memory and residency

No. setenv is a host-side operation. GPU residency offers no benefit, and RunMat gathers GPU-backed values automatically if they appear as inputs.

Examples

Set a new environment variable for the current session

status = setenv("RUNMAT_MODE", "development")

Expected output:

status =
     0

Update an existing environment variable

status = setenv("PATH", string(getenv("PATH")) + ":~/runmat/bin")

Expected output:

status =
     0

Remove an environment variable with an empty value

[status, message] = setenv("OLD_SETTING", "")

Expected output:

status =
     0

message =

Capture diagnostic messages when a name is invalid

[status, message] = setenv("INVALID=NAME", "value")

Expected output:

status =
     1

message =
Environment variable names must not contain '='.

Use character vectors from legacy code

status = setenv('RUNMAT_LEGACY', 'enabled')

Expected output:

status =
     0

Combine setenv with child process launches

setenv("RUNMAT_DATASET", "demo");
status = system("runmat-cli process-data")

Expected output:

status =
     0

FAQ

What status codes does setenv return?

0 means success; 1 means the operating system rejected the request (for example, due to an invalid name or an oversized value on Windows).

Does setenv throw errors?

Only when the inputs are the wrong type (non-text). Platform failures are reported through the status and message outputs so scripts can handle them programmatically.

How do I remove a variable?

Pass an empty string or empty character vector as the value.

Are names case-sensitive?

RunMat defers to the operating system: case-sensitive on Unix-like systems and case-insensitive on Windows.

Can I include trailing spaces in the value?

Use string scalars to preserve trailing spaces. Character vector inputs trim trailing padding spaces by design.

Does setenv affect the parent shell?

No. Changes are limited to the current RunMat process and any child processes launched afterwards.

What characters are disallowed in names?

setenv rejects names containing = or null characters. Additional platform-specific restrictions are enforced by the operating system and reported through the status/message outputs.

Can I call setenv from GPU-enabled code?

Yes. Arguments are gathered from the GPU before updating the environment; the operation itself always runs on the CPU.

How can I check whether the update succeeded?

Inspect the returned status. When it is 1, read the accompanying message to determine why the operation failed.

Will the variable persist after I exit RunMat?

No. Environment modifications are scoped to the current process.

Related functions to explore

These functions work well alongside setenv. Each page has runnable examples you can try in the browser.

getenv, mkdir, pwd, addpath, cd, copyfile, delete, dir, exist, fullfile, genpath, ls, movefile, path, rmdir, rmpath, savepath, tempdir, tempname

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how setenv works, line by line, in Rust.

• View setenv.rs on GitHub
• Learn how the 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 — faster, on any GPU, with no license required.

• Simulations that took hours now take minutes. RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed.
• Start running code in seconds. Open the browser sandbox or download a single binary. No license server, no IT ticket, no setup.
• A full development environment. GPU-accelerated 2D and 3D plotting, automatic versioning on every save, and a browser IDE you can share with a link.

Getting started · Benchmarks · Pricing