Home / Guides
PowerShell rename files from a CSV list
Last updated .
If you already keep a list of old and new names in a spreadsheet, PowerShell can do the rename — but the
naive one-liner drops two safety nets that matter at scale. This page shows the correct Import-Csv
loop with -LiteralPath, the traps it still leaves open, and how to skip the hand-writing entirely by
generating the script from a preview.
The correct Import-Csv loop
The common recipe reads the mapping with Import-Csv and calls Rename-Item for each row.
Two details separate a script that works from one that quietly loses a file: use -LiteralPath (so a
name with [ or ] is not treated as a wildcard) and pass only the new name to
-NewName, never a path.
Import-Csv .\map.csv | ForEach-Object {
Rename-Item -LiteralPath $_.Old -NewName $_.New
}
That handles the simple case. What it does not handle is the two failures that actually cost people files:
a target that already exists (PowerShell overwrites without asking), and rows that depend on each other, such as
a→b in one row and b→c in another. Run those top to bottom and the first rename eats the
file the second row still needed.
A script that refuses to overwrite
The generated script adds a guard before every step: it checks the target with Test-Path -LiteralPath,
and if the name is already taken it prints a warning and stops rather than overwrite. Chain and swap rows are
pre-sorted into a safe order (or routed through a temporary name), so a→b together with
b→c lands correctly. Matching names in the mapping that only differ by letter case are split into two
steps too, which is required on case-insensitive drives.
You do not write any of this by hand. Build the mapping in the
browser tool, check the preview, then use
Get a rename script to download rename.ps1 plus an undo.ps1 and a short
README. The free script covers the first 50 files of a batch; put both files in the folder and run
powershell -ExecutionPolicy Bypass -File .\rename.ps1.
Building the mapping itself is easier with a starting list: this guide on renaming from a CSV covers the two-column format the tool expects, and renaming from Google Sheets shows how to paste rows straight in.
Questions about renaming with PowerShell
Do I need to install anything to run the script?
No. A PowerShell script is a plain text file that runs with the PowerShell already on Windows. You only download it and run it; the script never uploads your files anywhere.
Why not just pipe Import-Csv straight into Rename-Item?
Because a one-liner ignores two real traps: two rows can resolve to the same name and silently overwrite a file, and chained renames such as a to b while b to c will clobber each other unless they run in the right order. The generated script checks every target first and stops on the first problem.
Does the script overwrite files if a target already exists?
Never. Each step checks Test-Path for the target before renaming; if it already exists the script prints a warning and exits instead of overwriting. That is the main difference from a hand-written loop.
How do I undo a run?
The download includes an undo script that reverses the same list. Run it in the same folder to put every file back. If a step failed partway, run undo first, then fix the mapping and try again.
How many files can the free script cover?
The free script covers the first 50 files of a batch, the same limit as the ZIP download and in-place modes. Unlock to include the rest of the list.