Python shutil Module

The shutil module in Python provides a collection of high-level operations for file and directory management. It includes functions to copy, move, and delete files and directories, as well as functions to create and extract archives.

Table of Contents

1. Introduction
2. Key Functions
   • copy
   • copy2
   • copyfile
   • copyfileobj
   • copymode
   • copystat
   • copytree
   • move
   • rmtree
   • make_archive
   • unpack_archive
   • disk_usage
   • which
3. Examples
   • Copying Files
   • Moving Files and Directories
   • Deleting Directories
   • Creating and Extracting Archives
   • Checking Disk Usage
4. Real-World Use Case
5. Conclusion
6. References

Introduction

The shutil module is designed to perform high-level file operations, making it easier to manage files and directories. It includes a variety of functions for copying, moving, and deleting files, as well as creating and extracting archives.

Key Functions

copy

Copies the content of the source file to the destination file.

import shutil

shutil.copy('source.txt', 'destination.txt')

copy2

Copies the source file to the destination file, preserving metadata (timestamps).

import shutil

shutil.copy2('source.txt', 'destination.txt')

copyfile

Copies the content of the source file to the destination file, but doesn't copy metadata.

import shutil

shutil.copyfile('source.txt', 'destination.txt')

copyfileobj

Copies the content of one file object to another.

import shutil

with open('source.txt', 'rb') as src, open('destination.txt', 'wb') as dst:
    shutil.copyfileobj(src, dst)

copymode

Copies the permission bits from the source file to the destination file.

import shutil

shutil.copymode('source.txt', 'destination.txt')

copystat

Copies the metadata (permissions, last access time, last modification time) from the source file to the destination file.

import shutil

shutil.copystat('source.txt', 'destination.txt')

copytree

Recursively copies an entire directory tree rooted at the source directory to the destination directory.

import shutil

shutil.copytree('source_dir', 'destination_dir')

move

Moves a file or directory to another location.

import shutil

shutil.move('source.txt', 'destination.txt')

rmtree

Recursively deletes a directory tree.

import shutil

shutil.rmtree('directory_to_delete')

make_archive

Creates an archive file (e.g., zip or tar) from a directory.

import shutil

shutil.make_archive('archive_name', 'zip', 'directory_to_archive')

unpack_archive

Unpacks an archive file (e.g., zip or tar) to a directory.

import shutil

shutil.unpack_archive('archive_name.zip', 'extract_to_directory')

disk_usage

Returns a named tuple with the total, used, and free disk space in bytes.

import shutil

usage = shutil.disk_usage('/')
print(f"Total: {usage.total}, Used: {usage.used}, Free: {usage.free}")

which

Returns the path to an executable which would have been run if the given command had been entered at the command line.

import shutil

print(shutil.which('python'))  # /usr/bin/python (example)

Examples

Copying Files

import shutil

# Copy file with metadata
shutil.copy2('source.txt', 'destination.txt')

# Copy file without metadata
shutil.copyfile('source.txt', 'destination_no_meta.txt')

Moving Files and Directories

import shutil

# Move a file
shutil.move('source.txt', 'destination.txt')

# Move a directory
shutil.move('source_dir', 'destination_dir')

Deleting Directories

import shutil

# Remove a directory tree
shutil.rmtree('directory_to_delete')

Creating and Extracting Archives

import shutil

# Create a zip archive
shutil.make_archive('archive_name', 'zip', 'directory_to_archive')

# Extract a zip archive
shutil.unpack_archive('archive_name.zip', 'extract_to_directory')

Checking Disk Usage

import shutil

# Check disk usage
usage = shutil.disk_usage('/')
print(f"Total: {usage.total / (1024 ** 3):.2f} GB")
print(f"Used: {usage.used / (1024 ** 3):.2f} GB")
print(f"Free: {usage.free / (1024 ** 3):.2f} GB")

Real-World Use Case

Backup and Restore

import shutil
import os

def backup_directory(source_dir, backup_dir):
    # Create a zip archive of the source directory
    shutil.make_archive(backup_dir, 'zip', source_dir)
    print(f"Backup of {source_dir} created at {backup_dir}.zip")

def restore_backup(backup_zip, restore_dir):
    # Extract the zip archive to the restore directory
    shutil.unpack_archive(backup_zip, restore_dir)
    print(f"Backup {backup_zip} restored to {restore_dir}")

# Backup a directory
backup_directory('important_data', 'backup/important_data_backup')

# Restore the backup
restore_backup('backup/important_data_backup.zip', 'restored_data')

Conclusion

The shutil module in Python provides a comprehensive set of functions for high-level file operations, including copying, moving, deleting, and archiving files and directories. It simplifies file and directory management tasks, making it used for many applications.

References

• Python shutil module documentation