ls — List files and folders in MATLAB and RunMat.
ls lists directory contents. With no inputs it lists the current folder; with an input path or wildcard it lists matching entries. Output formatting and char-array return behavior follow MATLAB semantics.
Syntax
listing = ls()
listing = ls(name)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
name | StringScalar | Yes | — | Folder, file path, or wildcard pattern to list. |
Returns
| Name | Type | Description |
|---|---|---|
listing | Any | Character array containing one listed entry per row. |
Errors
| Identifier | When | Message |
|---|---|---|
| — | More than one input argument is provided. | ls: too many input arguments |
| — | Name argument is not a character vector or string scalar. | ls: name must be a character vector or string scalar |
How ls works
lswithout outputs displays the directory listing in the REPL. When you assign the result to a variable, you receive a character array with one row per item, padded with spaces to a fixed width.ls(name)accepts character vectors or string scalars. The argument may be an absolute path, a relative path, or a wildcard such as*.morbuild/*.- Paths beginning with
~or~/expand to the current user's home directory, matching MATLAB desktop behaviour on every supported platform. - Wildcards follow MATLAB rules:
*matches any sequence of characters and?matches exactly one character. The pattern is evaluated relative to the current folder unless it contains a leading path. - Directory results include the platform-specific file separator (
/on Unix,\on Windows) so you can quickly distinguish folders from files, and duplicate matches are removed automatically. - Empty matches return a
0×0character array rather than raising an error, enabling idioms such asisempty(ls("*.tmp")). - Only scalar inputs are supported. Multi-row character arrays, multi-element string arrays, numeric values, or logical arguments raise
ls: name must be a character vector or string scalar, mirroring MATLAB's diagnostics.
Does RunMat run ls on the GPU?
ls is an I/O-centric builtin with no GPU execution path. When the argument is a GPU-resident scalar (for example, the output of gather that remained on the device), RunMat gathers it to the host before expanding wildcards. No device kernels run, and acceleration providers do not need to implement hooks for this builtin.
GPU memory and residency
No. Directory listings are always computed on the CPU. Passing gpuArray("*.m") offers no benefit: RunMat will gather the value automatically before enumerating files, and results are materialised as host-resident character arrays.
Examples
List Files In The Current Folder
fid = fopen("README.md", "w"); fclose(fid);
mkdir("src");
mkdir("tests");
lsExpected output:
README.md
src/
tests/List Only MATLAB Files Using Wildcards
fid = fopen("script.m", "w"); fclose(fid);
fid = fopen("solver.m", "w"); fclose(fid);
fid = fopen("test_helper.m", "w"); fclose(fid);
ls("*.m")Expected output:
script.m
solver.m
test_helper.mCapture A Directory Listing In A Variable
fid = fopen("README.md", "w"); fclose(fid);
listing = ls;
disp(listing(1, :)); % Display the first entryExpected output:
README.mdList The Contents Of A Specific Folder
mkdir("tmp");
fid = fopen(fullfile("tmp", "tmpfile.txt"), "w"); fclose(fid);
mkdir(fullfile("tmp", "subdir"));
tempDir = fullfile(pwd, "tmp");
ls(tempDir)Expected output:
tmpfile.txt
subdir/Use Wildcards With Nested Paths
mkdir(fullfile("src", "utils"));
fid = fopen(fullfile("src", "main.rs"), "w"); fclose(fid);
fid = fopen(fullfile("src", "utils", "helpers.rs"), "w"); fclose(fid);
ls("src/**/*.rs")Expected output:
src/main.rs
src/utils/helpers.rsHandle Missing Matches Gracefully
if isempty(ls("*.tmp"))
disp("No temporary files found.");
endExpected output:
No temporary files found.Combine ls With cd For Temporary Directory Changes
mkdir("examples");
fid = fopen(fullfile("examples", "animation.m"), "w"); fclose(fid);
fid = fopen(fullfile("examples", "plot_surface.m"), "w"); fclose(fid);
start = cd("examples");
cleanup = onCleanup(@() cd(start));
files = ls("*.m")Expected output:
animation.m
plot_surface.mUsing ls with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how ls changes the result.
Run a small ls example, explain the result, then change one input and compare the output.
FAQ
What types can I pass to ls?⌄
Use character vectors or string scalars. Other types – including numeric values, logical arrays, or string arrays with multiple elements – produce an error.
Does ls support wildcard patterns?⌄
Yes. Use * to match any sequence and ? for a single character. Patterns are resolved relative to the current folder unless you provide an absolute path.
How are directories indicated in the output?⌄
Directory entries end with the platform-specific file separator (/ or \) so you can distinguish them from files.
What happens if there are no matches?⌄
The function returns a 0×0 character array. You can test for this with isempty or by checking size.
Can I list the contents of another drive or mounted volume?⌄
Yes. Provide the absolute path, e.g., ls("D:\Projects") on Windows or ls("/Volumes/Data") on macOS.
Does ls follow symbolic links?⌄
The function reports the link itself; if the link points to a directory, it receives the directory suffix but the listing does not recursively expand the target.
Will ls respect the current working directory set by cd?⌄
Absolutely. ls always evaluates relative paths against whatever pwd reports.
Is the output sorted?⌄
Yes. RunMat sorts case-insensitively on Windows and case-sensitively on Unix-like systems to match MATLAB conventions.
How do I list hidden files?⌄
Hidden files are included when they match the pattern you specify. On Unix-like systems, prepend a dot: ls(".*").
Can I send the output directly to another builtin?⌄
Yes. Because the result is a character array, you can convert it to a string array with string(ls) or operate on individual rows using indexing.
Related Io functions
Repl Fs
addpath · cd · copyfile · delete · dir · exist · fileattrib · fileparts · fullfile · genpath · getenv · getpref · isenv · isfile · isfolder · ispref · matlabroot · memmapfile · mkdir · movefile · 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 ls is executed, line by line, in Rust.
- View the source for ls 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.