movefile — Move or rename files and folders in MATLAB and RunMat.

movefile renames files/folders or moves them to new locations. Status/message outputs and optional force-overwrite behavior follow MATLAB semantics.

Syntax

status = movefile(source, destination)
status = movefile(source, destination, flag)
[status, msg, msgID] = movefile(source, destination)
[status, msg, msgID] = movefile(source, destination, flag)

Inputs

Returns

Returned values from movefile depend on how many outputs the caller requests.

Errors

How movefile works

• status = movefile(source, destination) moves or renames source. status is a double scalar that is 1 on success and 0 on failure.
• [status, message, messageID] = movefile(...) also returns MATLAB-style diagnostic text. Successful operations populate both strings with empty character arrays (1×0).
• movefile(source, destination, 'f') forces the move, overwriting an existing destination file or folder. Without the flag, movefile refuses to overwrite existing targets.
• Wildcards in source (such as *.m) expand to matching filesystem entries. When the pattern resolves to multiple items, destination must be an existing folder and movefile moves each match into that folder.
• Inputs accept character vectors or string scalars. Other types raise MATLAB-style errors before any filesystem work occurs.
• Paths are resolved relative to the current working directory (pwd) and expand a leading ~ into the user's home directory.
• Filesystem failures—including missing files, permission errors, or read-only destinations—return status = 0 plus descriptive diagnostics; only invalid inputs raise immediate errors.

Does RunMat run movefile on the GPU?

movefile performs host-side filesystem operations. When acceleration providers are active, RunMat first gathers any GPU-resident arguments (for example, gpuArray("logs")), executes the move on the CPU, and returns host-resident outputs. Providers do not expose special hooks for this builtin, so GPU execution is not applicable.

GPU memory and residency

No. movefile always runs on the host CPU, so storing paths on the GPU offers no benefit. If a string argument is already GPU-resident, RunMat gathers it automatically before touching the filesystem so existing scripts continue to work unchanged.

Examples

Rename a file in the same folder

fid = fopen("results.txt", "w"); fclose(fid);
status = movefile("results.txt", "archive.txt")

Expected output:

status =
     1

Move a file into an existing folder

mkdir("reports");
fid = fopen("summary.txt", "w"); fclose(fid);
status = movefile("summary.txt", "reports")

Expected output:

status =
     1

Force overwrite an existing destination

fid = fopen("draft.txt", "w"); fclose(fid);
fid = fopen("final.txt", "w"); fclose(fid);
[status, message, messageID] = movefile("draft.txt", "final.txt", "f")

Expected output:

status =
     1
message =

messageID =

Move multiple files with a wildcard

mkdir("data");
fid = fopen("a.log", "w"); fclose(fid);
fid = fopen("b.log", "w"); fclose(fid);
status = movefile("*.log", "data")

Expected output:

status =
     1

Handle missing sources gracefully

[status, message, messageID] = movefile("missing.txt", "dest.txt")

Expected output:

status =
     0
message =
Source "missing.txt" does not exist.
messageID =
RunMat:MOVEFILE:FileDoesNotExist

Use gpuArray inputs for paths

fid = fopen("draft.txt", "w"); fclose(fid);
status = movefile(gpuArray("draft.txt"), gpuArray("final.txt"))

Expected output:

status =
     1

Using movefile with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how movefile changes the result.

FAQ

Related Io functions

Open-source implementation

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

• View the source for movefile 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