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
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
source | StringScalar | Yes | — | Source file/folder path or wildcard pattern. |
destination | StringScalar | Yes | — | Destination path. |
flag | StringScalar | Yes | "f" | Overwrite flag; only "f" is accepted. |
Returns
| Name | Type | Description |
|---|---|---|
status | NumericScalar | 1 on success, 0 when move fails. |
msg | StringScalar | Diagnostic message for failures. |
msgID | StringScalar | Stable diagnostic identifier string. |
Returned values from movefile depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:movefile:NotEnoughInputs | Fewer than two input arguments are provided. | movefile: not enough input arguments |
RunMat:movefile:TooManyInputs | More than three input arguments are provided. | movefile: too many input arguments |
RunMat:movefile:SourceArgType | Source argument is not a character vector or string scalar. | movefile: source must be a character vector or string scalar |
RunMat:movefile:DestinationArgType | Destination argument is not a character vector or string scalar. | movefile: destination must be a character vector or string scalar |
RunMat:movefile:FlagArgType | Flag argument is not the scalar character 'f'. | movefile: flag must be the character 'f' supplied as a char vector or string scalar |
RunMat:movefile:OSError | Filesystem move operation fails. | movefile: unable to move |
RunMat:movefile:FileDoesNotExist | Source path or wildcard match does not exist. | movefile: source not found |
RunMat:movefile:DestinationExists | Destination already exists and overwrite is not requested. | movefile: destination already exists |
RunMat:movefile:DestinationNotFound | Destination directory is missing for wildcard source moves. | movefile: destination folder not found |
RunMat:movefile:DestinationNotDirectory | Destination must be a directory for wildcard move mode. | movefile: destination is not a directory |
RunMat:movefile:EmptySource | Source path is empty. | Source file or folder name must not be empty. |
RunMat:movefile:EmptyDestination | Destination path is empty. | Destination file or folder name must not be empty. |
RunMat:movefile:InvalidPattern | Source wildcard pattern is invalid. | movefile: invalid source pattern |
How movefile works
status = movefile(source, destination)moves or renamessource.statusis a double scalar that is1on success and0on 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,movefilerefuses to overwrite existing targets.- Wildcards in
source(such as*.m) expand to matching filesystem entries. When the pattern resolves to multiple items,destinationmust be an existing folder andmovefilemoves 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 = 0plus 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 =
1Move a file into an existing folder
mkdir("reports");
fid = fopen("summary.txt", "w"); fclose(fid);
status = movefile("summary.txt", "reports")Expected output:
status =
1Force 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 =
1Handle 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:FileDoesNotExistUse gpuArray inputs for paths
fid = fopen("draft.txt", "w"); fclose(fid);
status = movefile(gpuArray("draft.txt"), gpuArray("final.txt"))Expected output:
status =
1Using movefile with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how movefile changes the result.
Run a small movefile example, explain the result, then change one input and compare the output.
FAQ
What status codes does movefile return?⌄
1 indicates every requested move succeeded; 0 indicates that nothing was moved. Status values are doubles so existing MATLAB scripts continue to work.
Does movefile throw exceptions?⌄
Only invalid inputs raise errors. Filesystem failures surface through the status, message, and message ID outputs.
How do I overwrite an existing file?⌄
Pass the 'f' flag as the third argument. Without it, movefile refuses to overwrite existing files or folders.
Can I move multiple files at once?⌄
Yes. Include wildcards such as *.txt in source. The destination must be an existing folder in that case.
Does movefile work with folders?⌄
Yes. It can move or rename entire folders. When moving into another folder and the target name already exists, pass 'f' to overwrite it.
How are paths resolved?⌄
Paths are resolved relative to pwd, and a leading ~ expands to the user's home directory.
Will GPU acceleration speed up movefile?⌄
No. The builtin executes on the host CPU. GPU-resident strings are gathered automatically before performing the move.
What happens if no files match a wildcard?⌄
The function returns status = 0, sets message to "Source \"pattern\" does not exist.", and leaves the filesystem unchanged.
Does the function preserve timestamps or permissions?⌄
Yes. movefile forwards the operation to the operating system, which preserves attributes when possible.
Can I move directories across volumes?⌄
When the underlying operating system reports an error (for example, moving across volumes without rename support), movefile returns status = 0 along with the system error text so you can handle it programmatically.
Related Io functions
Repl Fs
addpath · cd · copyfile · delete · dir · exist · fileattrib · fileparts · fullfile · genpath · getenv · getpref · isenv · isfile · isfolder · ispref · ls · matlabroot · memmapfile · mkdir · open · opentoline · path · pathsep · pcode · pwd · readstruct · rehash · restoredefaultpath · rmdir · rmpath · run · savepath · setenv · setpref · system · tempdir · tempname · uigetdir · uigetfile · uiputfile · unsetenv · userpath · what · winqueryreg · xmlread · xmlwrite
Tabular
arrayDatastore · csvread · csvwrite · detectImportOptions · dlmread · dlmwrite · fileDatastore · parquetDatastore · parquetinfo · parquetread · readcell · readmatrix · readtable · readtimetable · spreadsheetImportOptions · writecell · writematrix · writetable · writetimetable · xlsread · xlswrite
Filetext
fclose · feof · fgetl · fgets · fileread · filewrite · fopen · fprintf · fread · frewind · fwrite · readlines · writelines
Import
Json
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.