whos — List workspace or MAT-file variables with MATLAB-compatible metadata fields.
whos returns MATLAB-style variable metadata (name, size, bytes, class, flags) for current workspace values or MAT-file contents.
Syntax
vars = whos()
vars = whos(selector, ...)
vars = whos("-file", filename, selector, ...)
vars = whos("-regexp", pattern, ...)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
selector | StringScalar | Variadic | — | Name filters, wildcard patterns, or options. |
file_kw | StringScalar | Yes | "-file" | File mode option. |
filename | StringScalar | Yes | — | MAT-file path. |
regexp_kw | StringScalar | Yes | "-regexp" | Regexp mode option. |
pattern | StringScalar | Variadic | — | Regular-expression patterns. |
Returns
| Name | Type | Description |
|---|---|---|
vars | Any | Cell array of structs describing matching variables. |
Errors
| Identifier | When | Message |
|---|---|---|
| — | The '-file' option is provided without a filename. | whos: '-file' requires a filename |
| — | The '-file' option is provided more than once. | whos: '-file' may only be specified once |
| — | The '-regexp' option is provided without patterns. | whos: '-regexp' requires at least one pattern |
| — | The '-regexp' option receives only empty patterns. | whos: '-regexp' requires non-empty pattern strings |
| — | A regexp pattern fails to compile. | whos: invalid regular expression |
| — | An unsupported option token is provided. | whos: unsupported option |
| — | Filename argument is not a char row or string scalar. | whos: filename must be a character vector or string scalar |
| — | A selector cell contains a non-string-like element. | whos: selection cells must contain string or character scalars |
| — | Selector argument is not a char array/string/string array/cell thereof. | whos: selections must be character vectors, string scalars, string arrays, or cell arrays of those types |
| — | Wildcard selector pattern fails to parse. | whos: invalid pattern |
How whos works
whoswith no arguments lists every variable in the active workspace, using MATLAB's default alphabetical ordering.whos pattern1 pattern2 ...accepts character vectors or string scalars containing wildcard expressions (*,?,[abc]). Any variable whose name matches at least one pattern is reported.whos('-regexp', expr1, expr2, ...)keeps variables whose names match any of the supplied regular expressions.whos globallists only the variables that are marked as global within the active workspace.whos('-file', filename, ...)inspects a MAT-file without loading it. You can combine-filewith explicit names or-regexpselectors, mirroring MATLAB.- The returned struct array uses string scalars for textual fields (
name,class,nesting) and MATLAB-style numeric row vectors for thesizefield. bytesreports the amount of memory consumed by the value using RunMat's host representation. GPU arrays stay on the device; RunMat estimates bytes from the device-resident shape and provider precision.
Does RunMat run whos on the GPU?
whos is an introspection builtin that runs entirely on the CPU. When a variable is a gpuArray, RunMat leaves it on the device and derives metadata (element count, precision, and total bytes) from the handle and active provider. No kernels are launched and no device buffers are gathered. Auto-offload heuristics remain untouched.
GPU memory and residency
You do not need to move data to or from the GPU to call whos. The builtin gathers scalar arguments if they happen to live on the device, but the workspace variables themselves remain where they are. Use gather separately if you need host copies of the data for further processing.
Examples
List All Workspace Variables
a = 42;
b = rand(3, 2);
info = whos;
{info.name}Expected output:
{"a"} {"b"}Filter Variables With Wildcards
alpha = 1;
beta = 2;
results = whos("a*");
{results.name}Expected output:
{"alpha"}Use Regular Expressions To Match Names
x1 = rand;
x2 = rand;
matches = whos('-regexp', '^x\\d$');
cellstr({matches.name})Expected output:
{'x1'}
{'x2'}Inspect Variables Stored In A MAT-File
save('snapshot.mat', 'alpha', 'beta')
file_info = whos('-file', 'snapshot.mat');
{file_info.name}Expected output:
{"alpha"} {"beta"}Check GPU Arrays Without Gathering
G = gpuArray(rand(1024));
meta = whos('G');
meta.bytes % estimated bytes on deviceExpected output:
meta.bytes
ans =
8.3886e+06Using whos with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how whos changes the result.
Run a small whos example, explain the result, then change one input and compare the output.
FAQ
What fields does whos return?⌄
Each entry exposes name, size, bytes, class, global, sparse, complex, nesting, and persistent, matching MATLAB semantics.
Does whos mutate the workspace?⌄
No. It is a pure query that never creates, deletes, or modifies variables.
Are bytes identical to MATLAB?⌄
RunMat reports the size of its own representations. Numeric and logical arrays match MATLAB's byte counts; other types (such as structs or objects) may differ slightly because RunMat records their data differently.
How are global variables handled?⌄
Variables declared with global are marked with global = true. Use whos global to list only globals.
Can I combine wildcard filters and -regexp?⌄
Yes. whos('data*', '-regexp', '^(cfg|state)') reports the union of both selections.
What happens when no variables match?⌄
A 0×1 struct array is returned, just like MATLAB, so idioms such as isempty(whos('foo')) work.
Does whos('-file', ...) read the entire MAT-file?⌄
It parses only enough metadata to reconstruct variable values. Large arrays are streamed once; no workspace variables are modified.
How are persistent variables reported?⌄
RunMat currently marks all entries as persistent = false in the base workspace. Future releases will surface persistent metadata from function scopes.
Will GPU arrays be gathered?⌄
No. whos inspects device handles and leaves residency untouched.
Related Introspection functions
Open-source implementation
Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how whos is executed, line by line, in Rust.
- View the source for whos 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.