cd — Change or query the current working folder in MATLAB and RunMat.
cd displays the current working folder or switches to a different folder. Relative path resolution and session behavior follow MATLAB semantics for script and interactive workflows.
Syntax
folder = cd()
folder = cd(folder)Inputs
| Name | Type | Required | Default | Description |
|---|---|---|---|---|
folder | StringScalar | Yes | — | Target folder path. |
Returns
| Name | Type | Description |
|---|---|---|
folder | StringScalar | Previous working folder before any directory change. |
Errors
| Identifier | When | Message |
|---|---|---|
| — | More than one positional argument is provided. | cd: too many input arguments |
| — | Folder argument is not a character vector or string scalar. | cd: folder name must be a character vector or string scalar |
| — | Folder argument resolves to an empty string. | cd: folder name must not be empty |
| — | Target directory cannot be entered. | cd: unable to change directory |
| — | Current working directory cannot be resolved. | cd: unable to determine current directory |
How cd works
cdwith no input returns the absolute path of the current folder as a character row vector (1×N).cd(newFolder)changes the working folder and returns the previous folder, enabling the classic MATLAB patternold = cd(new); ...; cd(old);.- Accepts character vectors and string scalars. String arrays must contain exactly one element. Other types raise
cd: folder name must be a character vector or string scalar. - Supports relative paths (for example
cd('..')), absolute paths, and the shell-style~expansion to jump to the user home folder. - MATLAB command form is supported for path-like folder arguments, including
cd ..,cd ./data, andcd ~/project. - Emits descriptive errors when the folder does not exist or cannot be accessed.
- Does not modify GPU residency; path values always live on the host.
Does RunMat run cd on the GPU?
cd performs host-side path manipulation and process-level directory changes. When callers supply the folder argument from GPU memory, RunMat gathers the value before resolving the new path. Providers are not expected to implement hooks for this builtin, and no GPU kernels run as part of cd.
GPU memory and residency
cd operates entirely on the CPU, so there is no performance benefit to moving folder arguments onto the GPU. If a path value is already wrapped in gpuArray, RunMat transparently gathers it before resolving the change directory request. Scripts can keep using plain character vectors or string scalars without worrying about residency.
Examples
Displaying the current working folder
current = cdExpected output:
% current is the absolute path to the folder where RunMat is executingChange Directory To A Project Subfolder
projectRoot = pwd;
mkdir("data/logs");
old = cd("data/logs");
% ... work inside the logs folder ...
cd(old)Expected output:
% old contains the previous folder so you can restore it later, and the final cd(old)
% call brings you back to projectRootNavigate Up One Level From The Current Folder
old = cd("..")Expected output:
% RunMat moves to the parent folder and old captures the prior locationNavigate With MATLAB Command Syntax
projectRoot = pwd;
mkdir("scratch");
cd scratch
cd ..
backAtRoot = strcmp(pwd, projectRoot)Expected output:
backAtRoot =
logical
1Switch To Your Home Folder With cd ~
old = cd("~")Expected output:
% Changes to the user home directory; old stores the previous folderCapture The Previous Folder And Restore Later
old = cd("results");
% ... run code that writes outputs into results ...
cd(old)Expected output:
% The working folder is restored to its original location at the endHandle Missing Folders With A try/catch Block
try
cd("missing-folder");
catch err
disp(err.message);
endExpected output:
% Displays a descriptive error such as:
% "cd: unable to change directory to 'missing-folder' (No such file or directory)"Using cd with coding agents
Open a RunMat example with live inputs, then ask the agent to explain how cd changes the result.
Run a small cd example, explain the result, then change one input and compare the output.
FAQ
Does cd return the new folder or the old folder?⌄
When you pass an input, cd returns the previous folder so that you can restore it later. Calling cd with no input returns the current folder.
Can I pass GPU-resident strings to cd?⌄
Yes. RunMat gathers any GPU scalar arguments automatically before resolving the path.
Is tilde (~) expansion supported?⌄
Yes. cd('~') and cd('~/subdir') jump to the user home folder. Other leading ~ patterns are treated literally so existing MATLAB scripts continue to work on platforms that support them.
How are relative paths resolved?⌄
Relative folders are interpreted with respect to whatever cd reports as the current folder, exactly like MATLAB.
What happens if the target folder does not exist?⌄
cd throws an error that includes both the requested folder and the underlying operating system message.
Can I change to folders whose names include spaces?⌄
Yes. Provide them as strings or character vectors—RunMat preserves whitespace exactly.
Related Io functions
Repl Fs
addpath · 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 · 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 cd is executed, line by line, in Rust.
- View the source for cd 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.