Batch Renaming Files Script

diagram batch renaming, and the two ways it destroys data mermaid

  flowchart TD
  A["collect the files"] --> B["build the full old -> new mapping"]
  B --> C{"any duplicate targets?"}
  C -->|yes| D["stop -- two files want the same name"]
  C -->|no| E{"does any target already exist?"}
  E -->|yes| F["stop, or rename via a temporary name"]
  E -->|no| G{"does any target collide with a source?"}
  G -->|yes| H["two-pass: everything to temp names, then to finals"]
  G -->|no| I["print the plan"]
  H --> I
  I --> J{"--apply given?"}
  J -->|no| K["done -- nothing changed"]
  J -->|yes| L["os.replace for deliberate overwrite, os.rename otherwise"]

Renaming in a loop has two failure modes that a first version almost always has. A target that already exists is either an error or a silent overwrite depending on the platform and the call. And a sequence like 1->2, 2->3 can consume its own inputs if the order is wrong. Both are avoided by planning the whole mapping first.

Measured on Windows: renaming onto an existing file raised

text

FileExistsError: Cannot create a file when that file already exists

On POSIX the same call silently replaces the destination. That difference is the reason a batch-rename script can pass every test on a laptop and quietly destroy files on a server.

Use the call that says what you mean:

os.replace(src, dst) — overwrite the destination, the same way everywhere.
os.rename(src, dst) — platform-dependent; fine only when you have already checked that dst does not exist.

And plan the whole mapping before touching anything. A loop that renames 1 -> 2 and then 2 -> 3 has already destroyed the original 2.

Problem

You have files like:

IMG_0001.JPG
IMG_0002.JPG

You want:

photo_0001.jpg
photo_0002.jpg

Safe renamer

batch_rename.py

from pathlib import Path
 
 
def batch_rename(folder: Path, prefix: str, dry_run: bool = True):
    files = sorted([p for p in folder.iterdir() if p.is_file()])
 
    for i, p in enumerate(files, start=1):
        new_name = f"{prefix}_{i:04d}{p.suffix.lower()}"
        target = p.with_name(new_name)
 
        if dry_run:
            print("[DRY RUN]", p.name, "->", target.name)
        else:
            p.rename(target)
 
 
batch_rename(Path("./demo"), prefix="photo", dry_run=True)

Batch Renaming Files Script

Problem

Safe renamer

Tips

🧪 Try It Yourself

Exercise 1 – List Files with os.listdir

Exercise 2 – Join Paths with os.path.join

Exercise 3 – Write and Read a File

pch.feedbackHeading