The os.rename() is a built-in Python function that renames a source directory or a file to a specified destination directory or file. It is a cross-platform function that allows moving files or directories to a new location within the same filesystem.

Syntax

os.rename(src, dst, src_dir_fd=None, dst_dir_fd=None)

Parameters

Argument	Description
src (str or bytes)	It represents a current directory path whose file or directory is to be renamed.
dst (str or bytes)	It represents a new file or directory path.
src_dir_fd (int, optional)	It is a file descriptor referring to a directory, used as the base for src (Unix only).
dst_dir_fd (int, optional)	It is a file descriptor referring to a directory, used as the base for dst (Unix only).

Renaming a file

We can rename a file by passing the path of the old file and the path of the new file.

Here is the current state of the file before renaming:

As you can see from the above screenshot that we have a file called “file.txt”. We will rename it to “new_file.txt”.

import os

# Renaming 'file.txt' to 'new_file.txt'
os.rename('dir1/file.txt', 'dir1/new_file.txt')

print("File renamed successfully.")

# Output: File renamed successfully.

What if new_file.txt already exists? Well, this behavior depends on the OS (Unix: overwrite; Windows: error).

Moving and renaming a file

The os.rename() function not only renames a file but also moves it to a different directory with a specified name. Let’s say we have a file called new_file.txt in our current directory.

Let’s move the new_file.txt to a new_dir folder with the latest_file.txt file name.

import os

os.rename('dir1/new_file.txt', 'dir1/new_dir/latest_file.txt')

print("File moved successfully.")

# Output: File moved successfully.

After moving a file with a new name, the new_dir folder looks like this screenshot:

Renaming a directory

In the current state of the file system, we have a directory named “new_dir”.

Let’s rename an entire directory from “new_dir” to “latest_dir”.

import os

# Renaming a directory from 'new_dir' to 'latest_dir'
os.rename('dir1/new_dir', 'dir1/latest_dir')

print("Directory renamed from 'new_dir' to 'latest_dir'")

# Output: Directory renamed from 'new_dir' to 'latest_dir'

Handling overwrites

When it comes to existing files, it depends on the platform you are working on. If your renamed file already exists and your platform is Unix, it will overwrite it silently. However, if your OS is Windows, it may throw an OSError.

To handle potential errors, you can use the try-except mechanism.

import os

# Unix: Overwrites 'existing.txt' silently
# Windows: Raises OSError if 'existing.txt' exists

try:
    os.rename('source.txt', 'existing.txt')
except OSError as e:
    print(f"Error: {e}")

The output will depend on the Operating System you are using.

Non-existent source

While renaming a file, if the source file does not exist, it will raise a FileNotFoundError. To handle this type of error, use a try-except block.

In the dir1 directory, there is no file named not_exist.txt, yet we still attempt to rename it; this method will throw an error.

import os

try:
    os.rename('dir1/not_exist.txt', 'dir1/new.txt')
except FileNotFoundError as e:
    print(f"Error: {e}")

# Output: Error: [Errno 2] No such file or directory: 'not_exist.txt' -> 'new.txt'

Destination directory does not exist

What if you are trying to move a file and rename it to another folder, but that folder does not exist? Well, again, it will throw the error.

import os

try:
    os.rename('dir1/latest_file.txt', 'dir1/folder2/new.txt')
except FileNotFoundError as e:
    print(f"Error: {e}")

# Output: No such file or directory: 'dir1/latest_file.txt' -> 'dir1/folder2/new.txt'

That’s all!