Python shutil Module: Managing Files and Directories (With Examples)

The Python programming language offers a versatile set of libraries for handling files and directories. Among these, the shutil module stands out as a powerful tool for performing various file operations. In this tutorial, we will explore the capabilities of the shutil module in detail, covering its functions and methods with comprehensive examples.

Table of Contents

1. Introduction to shutil Module
2. Copying Files and Directories

• shutil.copy()
• shutil.copy2()
• shutil.copyfile()
• shutil.copytree()

1. Moving and Renaming Files and Directories

• shutil.move()
• shutil.rename()

1. Deleting Files and Directories

• shutil.rmtree()

1. Archiving and Extracting Files

• Creating Archives
  • shutil.make_archive()
• Extracting Archives
  • shutil.unpack_archive()

1. Working with Temporary Files and Directories

• shutil.mktemp()
• shutil.mkdtemp()

1. Handling Permissions and Metadata

• shutil.copystat()

1. Error Handling and Exceptions
2. Conclusion

1. Introduction to shutil Module

The shutil module is part of the Python Standard Library and provides a high-level interface for various file and directory operations. It abstracts the underlying operating system-specific details and makes it easier to work with files and directories across different platforms. The module is particularly useful for tasks such as copying, moving, renaming, deleting files, and working with archives.

To start using the shutil module, you need to import it:

import shutil

2. Copying Files and Directories

shutil.copy()

The shutil.copy() function allows you to copy a single file from a source location to a destination location. It preserves the file’s metadata, such as permissions and timestamps.

import shutil

source_file = 'source_folder/file.txt'
destination_folder = 'destination_folder/'

shutil.copy(source_file, destination_folder)

shutil.copy2()

Similar to shutil.copy(), the shutil.copy2() function also copies a file while preserving its metadata. However, it offers additional control by allowing you to provide a destination filename as well.

import shutil

source_file = 'source_folder/file.txt'
destination_file = 'destination_folder/renamed_file.txt'

shutil.copy2(source_file, destination_file)

shutil.copyfile()

If you need more control over the copying process, you can use shutil.copyfile(). This function lets you copy the contents of one file to another file. It does not preserve metadata.

import shutil

source_file = 'source_folder/file.txt'
destination_file = 'destination_folder/copied_file.txt'

shutil.copyfile(source_file, destination_file)

shutil.copytree()

To copy entire directories along with their contents, you can use shutil.copytree(). This function creates a new directory and recursively copies all files and subdirectories from the source directory to the destination directory.

import shutil

source_directory = 'source_folder/'
destination_directory = 'destination_folder/'

shutil.copytree(source_directory, destination_directory)

3. Moving and Renaming Files and Directories

shutil.move()

The shutil.move() function allows you to move a file or directory from a source location to a destination location. This operation effectively performs a “cut and paste” action.

import shutil

source_path = 'source_folder/file.txt'
destination_path = 'destination_folder/file.txt'

shutil.move(source_path, destination_path)

shutil.rename()

For renaming files or directories within the same location, you can use shutil.rename(). This function changes the name of the given file or directory.

import shutil

old_name = 'old_name.txt'
new_name = 'new_name.txt'

shutil.rename(old_name, new_name)

4. Deleting Files and Directories

shutil.rmtree()

To remove a directory and its contents, you can use shutil.rmtree(). Be cautious when using this function, as it irreversibly deletes all files and subdirectories within the specified directory.

import shutil

directory_to_delete = 'folder_to_delete/'

shutil.rmtree(directory_to_delete)

5. Archiving and Extracting Files

Creating Archives: shutil.make_archive()

Archiving files and directories is a common task when you need to package multiple files into a single file. The shutil.make_archive() function can create various types of archives, such as ZIP, TAR, and more.

import shutil

source_directory = 'files_to_archive'
output_archive_path = 'archive_folder/my_archive'

shutil.make_archive(output_archive_path, 'zip', source_directory)

Extracting Archives: shutil.unpack_archive()

To extract the contents of an archive, you can use shutil.unpack_archive(). This function takes the path to the archive file and the destination directory where the contents will be extracted.

import shutil

archive_file = 'my_archive.zip'
destination_directory = 'extracted_contents/'

shutil.unpack_archive(archive_file, destination_directory)

6. Working with Temporary Files and Directories

shutil.mktemp()

Sometimes, you might need to create a temporary file for a short-lived task. The shutil.mktemp() function generates a unique temporary filename.

import shutil

temp_file = shutil.mktemp()
print("Temporary File:", temp_file)

shutil.mkdtemp()

Similarly, shutil.mkdtemp() creates a temporary directory with a unique name. This is useful for tasks that involve temporary data storage.

import shutil

temp_directory = shutil.mkdtemp()
print("Temporary Directory:", temp_directory)

7. Handling Permissions and Metadata

shutil.copystat()

If you need to copy the metadata and permission information (except for timestamps) from one file to another, you can use shutil.copystat().

import shutil

source_file = 'source_folder/file.txt'
destination_file = 'destination_folder/copied_file.txt'

shutil.copy2(source_file, destination_file)
shutil.copystat(source_file, destination_file)

8. Error Handling and Exceptions

When using the shutil functions, it’s important to handle exceptions appropriately, especially when dealing with files and directories that may not exist or when encountering permission issues.

import shutil

try:
    source_file = 'non_existent_folder/file.txt'
    destination_folder = 'destination_folder/'
    shutil.copy(source_file, destination_folder)
except FileNotFoundError:
    print("Source file not found.")
except PermissionError:
    print("Permission denied.")

9. Conclusion

The shutil module in Python is a versatile tool that simplifies various file and directory operations, making it

easier to manage your data and perform tasks like copying, moving, renaming, and archiving files. With its high-level abstractions, the shutil module shields you from platform-specific complexities, allowing you to focus on your application’s logic. This tutorial covered the core functions of the shutil module along with detailed examples to help you get started on your file manipulation journey in Python.