Batch File Renaming with os and shutil

Batch file renaming is a common task in data preprocessing, file organization, and automation workflows. Python provides several built-in libraries that make this process straightforward and efficient. Two of the most commonly used libraries for file operations are os and shutil. This article explores how to use these libraries to perform batch file renaming tasks in Python, offering code examples and practical tips.

Understanding os and shutil

The os module in Python provides a way to interact with the operating system. It allows you to navigate directories, retrieve file names, rename files, and more. The shutil module is used for high-level file operations such as copying and moving files.

When renaming files, the os.rename() function is most commonly used. While shutil does not have a direct renaming method, it can be helpful for copying files with a new name before deleting the original, serving as a workaround for more complex renaming needs.

Basic File Renaming Using os

The simplest way to rename a file is using os.rename():

python
CopyEdit
import os

# Rename a single file
old_name = "example.txt"
new_name = "renamed_example.txt"
os.rename(old_name, new_name)

This changes the file name within the same directory. If the file is located elsewhere or you’re dealing with many files, you’ll need to provide the full path.

Batch Renaming Files in a Directory

To rename multiple files in a directory, you can use os.listdir() to list all files and loop through them:

python
CopyEdit
import os

folder_path = "/path/to/your/folder"

for count, filename in enumerate(os.listdir(folder_path)):
    if filename.endswith(".txt"):
        new_name = f"document_{count}.txt"
        src = os.path.join(folder_path, filename)
        dst = os.path.join(folder_path, new_name)
        os.rename(src, dst)

This script renames all .txt files in the folder to document_0.txt, document_1.txt, etc.

Adding Prefixes or Suffixes to Filenames

You might want to add a prefix or suffix to existing file names without losing the original name information:

python
CopyEdit
import os

folder_path = "/path/to/your/folder"
prefix = "new_"

for filename in os.listdir(folder_path):
    src = os.path.join(folder_path, filename)
    dst = os.path.join(folder_path, prefix + filename)
    os.rename(src, dst)

This adds new_ to the beginning of each file name.

Changing File Extensions

Changing the file extension of multiple files can also be done using os.path.splitext():

python
CopyEdit
import os

folder_path = "/path/to/your/folder"

for filename in os.listdir(folder_path):
    if filename.endswith(".txt"):
        base = os.path.splitext(filename)[0]
        new_name = base + ".md"
        os.rename(os.path.join(folder_path, filename), os.path.join(folder_path, new_name))

This changes all .txt files to .md in the specified directory.

Renaming Based on File Metadata

You can also rename files using metadata like modification time:

python
CopyEdit
import os
import time

folder_path = "/path/to/your/folder"

for filename in os.listdir(folder_path):
    filepath = os.path.join(folder_path, filename)
    mod_time = os.path.getmtime(filepath)
    formatted_time = time.strftime('%Y-%m-%d_%H-%M-%S', time.localtime(mod_time))
    ext = os.path.splitext(filename)[1]
    new_name = f"{formatted_time}{ext}"
    os.rename(filepath, os.path.join(folder_path, new_name))

This renames each file based on its last modification time.

Using shutil for Complex File Operations

While shutil does not directly rename files, it can be used to move files with a new name:

python
CopyEdit
import os
import shutil

source_folder = "/path/to/source"
destination_folder = "/path/to/destination"

for filename in os.listdir(source_folder):
    if filename.endswith(".jpg"):
        new_name = "image_" + filename
        src = os.path.join(source_folder, filename)
        dst = os.path.join(destination_folder, new_name)
        shutil.move(src, dst)

This script moves .jpg files from the source folder to the destination folder while renaming them in the process.

Error Handling

File operations can fail for several reasons, such as missing permissions or existing files with the same name. Use try-except blocks to handle such cases:

python
CopyEdit
import os

folder_path = "/path/to/your/folder"

for filename in os.listdir(folder_path):
    try:
        new_name = "prefix_" + filename
        os.rename(os.path.join(folder_path, filename), os.path.join(folder_path, new_name))
    except Exception as e:
        print(f"Failed to rename {filename}: {e}")

This ensures that the script continues to run even if one file cannot be renamed.

Excluding Specific Files

To avoid renaming certain files, you can add conditional checks:

python
CopyEdit
import os

folder_path = "/path/to/your/folder"
exclude_list = ["do_not_rename.txt", "important.docx"]

for filename in os.listdir(folder_path):
    if filename not in exclude_list:
        new_name = "edited_" + filename
        os.rename(os.path.join(folder_path, filename), os.path.join(folder_path, new_name))

Best Practices

• Back up files before batch renaming, especially when renaming in place.

• Use dry runs by printing the new names before actually renaming to verify the logic.

• Avoid name collisions by checking if the target filename already exists.

• Sanitize filenames to remove or replace characters that may not be allowed on certain file systems.

Conclusion

Python’s os and shutil modules offer powerful tools for automating batch file renaming. With careful planning, these scripts can save hours of manual labor. From simple renaming to metadata-based logic and error handling, these techniques provide flexibility for various scenarios. Whether you are organizing digital photos, preparing datasets, or managing large file systems, mastering batch renaming in Python is an essential skill for automation and efficiency.