uigetfile — Open a host file-selection dialog and return the selected file name and path.
uigetfile requests an open-file selection from the active RunMat filesystem provider and returns MATLAB-compatible output values. Interactive hosts can implement the provider hook to show a native or browser picker; noninteractive hosts return the standard cancellation values.
Syntax
file = uigetfile()
file = uigetfile(filter)
[file, path] = uigetfile(filter, title)
[file, path, index] = uigetfile(filter, title, defaultName)
[file, path, index] = uigetfile(filter, title, defaultName, "MultiSelect", value)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
filter | Any | No | "*.*" | File extension pattern, semicolon-delimited patterns, or an N-by-1/N-by-2 cell array of patterns and descriptions. |
title | StringScalar | No | — | Dialog title. |
defaultName | StringScalar | No | — | Initial file or directory path for the dialog. |
optionName | StringScalar | No | "MultiSelect" | Name-value option name. `MultiSelect` is supported. |
optionValue | Any | No | "off" | `"on"`, `"off"`, or a scalar logical/numeric value. |
Returns
| Name | Type | Description |
|---|---|---|
file | Any | Selected filename, cell array of filenames for multiple selections, or 0 when cancelled. |
path | Any | Directory containing the selected file, including a trailing separator, or 0 when cancelled. |
index | NumericScalar | One-based selected filter index, or 0 when cancelled. |
Returned values from uigetfile depend on how many outputs the caller requests.
Errors
| Identifier | When | Message |
|---|---|---|
RunMat:uigetfile:InvalidArgument | A filter, title, default path, or name-value option has an unsupported type or shape. | uigetfile: invalid argument |
RunMat:uigetfile:TooManyOutputs | More than three output arguments are requested. | uigetfile: too many output arguments |
RunMat:uigetfile:HostError | The active filesystem provider fails while opening the host file-selection UI. | uigetfile: file selection failed |
RunMat:uigetfile:InvalidSelection | The active filesystem provider returns a malformed or internally inconsistent file selection. | uigetfile: invalid file selection |
How uigetfile works
file = uigetfile()uses an all-files filter.uigetfile(filter)accepts a character vector, string scalar, semicolon-delimited pattern list, or an N-by-1/N-by-2 cell array of patterns and descriptions.uigetfile(filter, title, defaultName)forwards the dialog title and initial file or directory path to the filesystem provider.uigetfile(..., 'MultiSelect', 'on')allows multiple selected files. When multiple files are selected,fileis a cell array of character vectors. A single selected file is returned as a character vector.- The selected
pathoutput is the containing directory with a trailing path separator. Theindexoutput is the one-based selected filter index. - Cancellation returns numeric zero for
file,path, andindex, matching MATLAB. This is also the behavior for filesystem providers that do not implement an open-file picker.
GPU memory and residency
No. File-selection dialogs are host/UI operations and always execute outside GPU residency. The provider hook returns paths in the active filesystem namespace, so browser hosts that import user-selected files should map them into the mounted provider namespace before returning the path.
Examples
Select A Spreadsheet
[file, path] = uigetfile('*.xlsx', 'Select a spreadsheet');
if isequal(file, 0)
return;
end
scores = readtable(fullfile(path, file));Use Multiple Filters
filters = {'*.m;*.mlx', 'MATLAB files'; '*.txt', 'Text files'};
[file, path, index] = uigetfile(filters, 'Open source file');Allow Multiple Files
[files, path] = uigetfile('*.csv', 'Select CSV files', pwd, 'MultiSelect', 'on');
if isequal(files, 0)
return;
endUsing uigetfile with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how uigetfile changes the result.
Run a small uigetfile example, explain the result, then change one input and compare the output.
FAQ
What happens in noninteractive or headless RunMat hosts?⌄
RunMat returns the MATLAB cancellation values (0) unless the active filesystem provider implements selectFileOpen / select_file_open.
How does a browser host provide a real file picker?⌄
Install a filesystem provider with a selectFileOpen(request) function. Return null or false for cancellation, a string path for one file, an array of string paths for multiple files, or an object such as { paths: ['/data/a.csv'], filterIndex: 1 }.
Does uigetfile read the selected file?⌄
No. It only returns the selected file name and directory. Use fullfile(path, file) with readtable, fopen, load, or another file-reading builtin to consume the file.
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 · movefile · open · opentoline · path · pathsep · pcode · pwd · readstruct · rehash · restoredefaultpath · rmdir · rmpath · run · savepath · setenv · setpref · system · tempdir · tempname · uigetdir · 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 uigetfile is executed, line by line, in Rust.
- View the source for uigetfile 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.