Home / Guides

Rename multiple files from a CSV

Last updated 24 October 2026.

A CSV is the smallest useful interface for a file rename: two columns, one row per file, and it opens in Excel, Numbers, Google Sheets, or a text editor. This guide covers the CSV format the tool expects, the four things that actually go wrong in practise, and how to check for them before anything is renamed.

The format

old,new
DSC_0412,DSC_0412
whitby-abbey-sunrise-01,"whitby abbey sunrise, 01"
scan_0031,Invoice 2024-001
scan_0032,Invoice 2024-002

Any header names work as long as they look like "old" and "new" in some form; you can also override the column choice in the UI after it loads. Delimiters are sniffed, so comma, semicolon and tab all work. UTF-8 and UTF-8 with BOM are both handled (Excel on Windows writes the BOM).

Failure mode 1: case and Unicode

Matching is NFC-normalised and case-insensitive on the name without its extension. That means IMG_001.JPG on disk matches img_001 in your sheet, and a name with a decomposed accent (common when a file came from macOS) matches the composed form. If you ever see a file reported as unmatched when you are certain the name is right, the cause is almost always a non-breaking space or a Windows-1252 smart quote pasted in from a web page — the preview will show the byte-level difference in the "why" note.

Failure mode 2: two files, one name

If two rows resolve to the same new name — or one row resolves to a name that another file on disk already has — the tool flags a conflict and skips both. It never picks a winner. This is the single most important behaviour difference between a careful tool and a shell one-liner: a loop of mv commands will happily overwrite the first file with the second and tell you nothing.

Fixing a conflict usually means adding a discriminator to the new names (-01, -02) or fixing a duplicated row in the sheet. The report CSV lists the exact row numbers so you can go back to the spreadsheet.

Failure mode 3: names Windows will not accept

A rename that works on your Mac will fail when the folder is synced to a Windows machine or a NAS. The tool rejects these up front:

• any of < > : " / \ | ? * anywhere in the name;
• a trailing dot or trailing space (Windows silently strips them, so the file ends up with a different name than you asked for);
• the reserved device names CON, PRN, AUX, NUL, COM1–COM9, LPT1–LPT9 — including with an extension, because CON.txt is still reserved;
• a base name longer than 200 characters, to leave room for the extension inside the 255-byte limit.

It does not "fix" these for you. Silent repair is how a batch of 300 files ends up with three of them named untitled (2).

Failure mode 4: the half-done run

If a rename stops halfway — the tab crashes, the network share drops, you hit Cancel — you need to know what was done. Download the report CSV after a run: one row per file with its status, the reason, and the sheet row number. If you used "rename in place", the tool also shows a per-file progress log in the page.

Regardless of tooling, the rule is the same: keep a copy until you have checked the result.

Command-line equivalent

For reference, on macOS or Linux the same job is roughly:

tail -n +2 map.csv | while IFS=, read -r old new; do
  [ -e "$old"* ] || { echo "no match: $old"; continue; }
  mv -- "$old".* "$new".*
done

That version does not handle case-insensitive matching, duplicates, quoting inside names, or Windows illegal characters, and it overwrites silently. On Windows, Rename-Item in PowerShell is closer, but still needs -WhatIf discipline. If you are going to run a script anyway, export the plan from the tool first and eyeball it — that is the part with the value in it.

Open the CSV renamer →

Next: renaming from an Excel list · batch rename on Mac and Windows