How to Rename Files in Mac Terminal: mv, zsh Loops and zmv
To rename a file in the Mac Terminal, use the mv command with the current name and the new name: mv old-name.txt new-name.txt. It renames folders the same way. To rename many files at once, use a zsh for loop with mv, or zsh's built-in zmv function, which can preview every change with -n before it touches anything.
Everything here was tested in zsh 5.9, the default shell on macOS, on an APFS drive. Work on a copy of your files the first time: Terminal has no Undo.
Open Terminal in the right folder
Open Terminal from Applications > Utilities, or press Command+Space and type Terminal. Then move to the folder that holds your files:
cd ~/Documents/Invoices
lsA quick shortcut: type cd (with a trailing space), drag the folder from Finder into the Terminal window, and press Return. Terminal pastes the full path with any spaces already escaped. You can also Control-click a folder in Finder and choose Services > New Terminal at Folder, if that service is turned on in Keyboard settings.
Rename one file with mv
mv report.txt report-2026.txtmv prints nothing when it succeeds. Check with ls. The same command renames a folder:
mv "Client Work" client-workUseful mv options
-iasks before overwriting a file that already has the new name.-nnever overwrites; if the new name is taken, nothing happens.-vprints what it did, for examplea.jpg -> c.jpg.
By default, mv silently replaces an existing file with the new name, so mv -iv (or -nv in scripts) is a good habit.
The folder trap
If the new name is an existing folder, mv doesn't rename: it moves your file or folder inside that folder. mv "Client Work" Archive puts Client Work inside Archive if Archive exists. Run ls first when in doubt.
Quoting names with spaces and special characters
The shell splits on spaces, so names with spaces must be quoted or escaped:
mv "Screen Shot 2026-11-08.png" screenshot-2026-11-08.png
mv Screen\ Shot\ 2026-11-08.png screenshot-2026-11-08.pngBoth do the same thing. Easier still: type the first few letters and press Tab; zsh completes the name and adds the backslashes for you.
Single quotes stop the shell from interpreting anything inside, which matters for names containing $, ! or backticks. A name that starts with a dash (-draft.txt) looks like an option to mv; put -- before the names: mv -- -draft.txt draft.txt.
Case-only renames on a Mac
APFS, the Mac's file system, is case-insensitive by default: Report.TXT and report.txt are the same name to it. That can make changing only the capitalisation awkward. In testing on current macOS, a plain mv does the job:
mv Report.TXT report.txtBut mv -n and mv -i see that report.txt "already exists" (it's the same file) and refuse or prompt, and some scripts and tools behave the same way. The method that always works is a two-step rename through a temporary name:
mv report.txt tmp-rename && mv tmp-rename Report.txtThe && only runs the second step if the first succeeded.
Rename many files with a zsh loop
A for loop runs mv once per file. This adds a 2026- prefix to every PDF in the folder:
for f in *.pdf; do mv -n -- "$f" "2026-$f"; doneAlways put "$f" in double quotes so names with spaces stay in one piece, and use -- for names that start with a dash.
Preview first with echo
Put echo in front of mv and the loop prints the commands instead of running them:
for f in *.pdf; do echo mv -n -- "$f" "2026-$f"; doneWhen the output looks right, press the Up arrow, delete echo and run it again.
Replace text in names
zsh's ${f//old/new} replaces every occurrence of old in $f. Replace spaces with hyphens:
for f in *\ *; do mv -n -- "$f" "${f// /-}"; doneNumber files in sequence
This renames JPGs to trip-001.jpg, trip-002.jpg and so on. The (n) glob qualifier sorts numerically, so img_2 comes before img_10:
i=1
for f in img_*.jpg(n); do
mv -n -- "$f" "$(printf 'trip-%03d.jpg' $i)"
((i++))
doneWithout (n), zsh sorts alphabetically and img_10 would be numbered before img_2. More ordering options are in the sequential renaming guide.
"no matches found"
If no file matches the pattern, zsh stops with an error such as zsh: no matches found: *.gif rather than running the loop. That's usually what you want. To make an empty match simply do nothing, add the (N) qualifier: for f in *.gif(N); do ... done.
Bulk rename with zmv
zmv is a function that ships with zsh. It renames files by pattern, checks for collisions before doing anything, and has a proper dry-run mode. Load it once per session (or add the line to ~/.zshrc):
autoload -U zmvThe basic form is zmv 'pattern' 'replacement'. Put both in single quotes. Parts of the pattern in parentheses become $1, $2 and so on in the replacement.
Change an extension (preview with -n, then run without it):
zmv -n '(*).jpeg' '$1.jpg'
zmv '(*).jpeg' '$1.jpg'The preview prints the exact commands:
mv -- a.jpeg a.jpg
mv -- b.jpeg b.jpgAdd a prefix:
zmv -n '(*).jpg' 'holiday-$1.jpg'Replace spaces with hyphens (in the replacement, $f is the whole original name):
zmv -n '* *' '${f// /-}'Lowercase names, including case-only changes, which zmv handled correctly on APFS in testing:
zmv -n '(*)' '${(L)1}'Include subfolders with **/, which matches any depth of folders:
zmv -n '(**/)(*).txt' '$1$2.md'Simple wildcard mode with -W, where each * in the replacement stands for what the matching * matched:
zmv -W -n '*.jpeg' '*.jpg'zmv's safety checks
zmv refuses to run if a rename would overwrite an existing file or if two files would end up with the same name, and it renames nothing at all in that case:
zmv: error(s) in substitution:
b.jpg and a.jpg both map to same.jpgThat makes it safer than a hand-written loop for big jobs. Combined with -n, you can iterate on the pattern until the preview is exactly right.
Other useful Terminal tools
- Finder is often quicker: for a simple find-and-replace or numbering job, Finder's built-in Rename (select files, Control-click, Rename) has a live example and Undo. See the Mac bulk rename guide.
- The rename command: the Perl
renameutility common on Linux isn't installed on macOS, but you can get it with Homebrew (brew install rename). The Linux rename guide explains its syntax. - find for deep folder trees:
findlocates files anywhere below a folder by name; see how to find a file by name, whose basics apply to macOS too.
When rules aren't enough
Loops and zmv are perfect when the new name follows from the old one. They can't tell you that IMG_4821.jpg is a receipt or that scan0007.pdf is a lease. File Renamer AI reads the content of photos, PDFs and documents and suggests descriptive names, which you review before downloading. For rule-based renames without the command line, the free online bulk renamer runs in your browser and never uploads your files.
Frequently Asked Questions
How do I rename a file in Mac Terminal?
Use mv followed by the current name and the new name, for example mv report.txt report-2026.txt. Run it from the folder that contains the file, or give full paths. Quote names that contain spaces, and use mv -i if you want to be asked before overwriting an existing file.
How do I rename multiple files at once in Terminal?
Use a zsh loop such as for f in *.pdf; do mv -n -- "$f" "2026-$f"; done, or load zmv with autoload -U zmv and run something like zmv '(*).jpeg' '$1.jpg'. Preview first by adding echo before mv in a loop, or -n to zmv.
How do I rename a file with spaces in Terminal?
Put the name in quotes, for example mv "My File.txt" my-file.txt, or escape each space with a backslash. Typing the first letters and pressing Tab lets zsh complete the name and escape it for you.
What is zmv on a Mac?
zmv is a bulk rename function included with zsh, the default macOS shell. Load it with autoload -U zmv, then rename by pattern with zmv 'pattern' 'replacement'. The -n option previews the changes, and zmv refuses to run if any rename would overwrite another file.
How do I change only the capitalisation of a file name in Terminal?
A plain mv such as mv Report.TXT report.txt works on current macOS, but mv -n and some tools refuse because the drive is case-insensitive and treats both names as the same. The reliable method is two steps: mv report.txt tmp-rename && mv tmp-rename Report.txt.
Can I undo a rename in Terminal?
No. mv and zmv have no undo, so the only way back is to rename again. Preview changes with echo or zmv -n, keep a copy of important folders, and use mv -v so you have a printed record of what changed.
Related Posts
How to Rename Files in Linux: mv, rename, Bash Loops and GUI Tools
How to rename a file in Linux with mv, rename directories, use both rename commands safely, and bulk rename files with bash loops, find and GUI file renamers.
MacHow to Rename Multiple Files at Once on Mac (Batch Rename Guide)
How to rename multiple files at once on Mac: step-by-step batch rename with Finder, an Automator Quick Action, and zsh commands in Terminal, with examples.
AdvancedHow to Rename Files with Python: os.rename, pathlib and Bulk Scripts
Change a file name in Python with os.rename, os.replace or pathlib, then bulk rename files safely with loops, regex, a dry run, collision checks and undo logs.
Ready to organize your files?
Try AI renaming right away. No sign-up needed until you download.
Try It Free