Complete Guide to Copying Files in Python | How to Use the shutil Module and Handle Errors

By 佐川 直弘 | Naohiro Sagawa (運営者)

※記事内に広告を含みます。Amazonアソシエイトとして適格販売により収入を得ています。

1. Introduction

Python provides powerful tools for handling file operations with ease. Among them, file copying is one of the most common tasks. This article introduces efficient ways to copy files and directories using Python’s standard shutil module. We will cover practical code examples, techniques to prevent overwriting, error handling strategies, and even advanced file copying methods.

2. Preparing to Copy Files in Python

Importing the shutil Module

The shutil module is part of Python’s standard library, so no additional installation is required. You can import it using the following code:

import shutil

This module enables file copying, moving, and deleting operations. Additionally, combining it with the os module allows you to check for file and directory existence and improve error handling.

Benefits of the shutil Module

The shutil module is known for its intuitive operation and simple code structure. It is particularly useful when performing batch operations on files and directories.

3. Basic Usage of the shutil Module

How to Use shutil.copy()

shutil.copy() is a basic function for copying files. It copies the original file to the specified destination.

import shutil

# Copying a file
shutil.copy('original.txt', 'copy.txt')

If a file with the same name already exists at the destination, it will be overwritten.

How to Use shutil.copy2()

shutil.copy2() is a function that copies not only the file content but also metadata such as creation time and file permissions.

import shutil

# Copying a file along with its metadata
shutil.copy2('original.txt', 'copy_with_metadata.txt')

This function is useful when creating an exact duplicate of a file.

4. How to Copy an Entire Directory

Using shutil.copytree()

shutil.copytree() is used to recursively copy an entire directory, including all files and subdirectories.

import shutil

# Copying a directory
shutil.copytree('source_directory', 'destination_directory')

However, if a directory with the same name already exists at the destination, an error will occur, so it’s important to check beforehand.

Excluding Specific Files or Directories During Copy

To exclude specific files or directories from being copied, use the ignore argument with shutil.ignore_patterns().

import shutil

# Copying a directory while ignoring .log files
shutil.copytree('source_directory', 'destination_directory', ignore=shutil.ignore_patterns('*.log'))

This code excludes all .log files while copying the directory.

5. Techniques to Prevent Overwriting

Using os.path.exists()

By default, shutil.copy() and shutil.copy2() will overwrite existing files if a file with the same name is already present at the destination. To prevent this, you should check for file existence beforehand.

import shutil
import os

# Check if the file already exists before copying
if not os.path.exists('copy.txt'):
    shutil.copy('original.txt', 'copy.txt')
else:
    print('File already exists. Skipping copy.')

Using pathlib.Path.exists()

The pathlib module provides a more intuitive way to check file existence.

from pathlib import Path

# Check existence using Path object
dst = Path('copy.txt')

if not dst.exists():
    shutil.copy('original.txt', dst)
else:
    print('File already exists. Skipping copy.')

6. How to Move Files in Python

Using shutil.move()

shutil.move() is used to move files or directories to a different location.

import shutil

# Move a file
shutil.move('original.txt', 'new_folder/original.txt')

If the destination directory does not exist, a FileNotFoundError will occur. It is recommended to check and create the directory beforehand if necessary.

import shutil
import os

# Check and create the destination directory if it doesn't exist
if not os.path.exists('new_folder'):
    os.makedirs('new_folder')

# Move the file
shutil.move('original.txt', 'new_folder/original.txt')

7. Practical Examples of File Copying in Python

Example: Copying a File

import shutil

# Copy a file
shutil.copy('data.txt', 'backup/data_backup.txt')

Example: Copying an Entire Directory

import shutil

# Copy a directory
shutil.copytree('project_files', 'project_backup')

Example: Preventing Overwriting

import shutil
import os

# Copy a file only if it does not already exist
if not os.path.exists('backup/report.txt'):
    shutil.copy('report.txt', 'backup/report.txt')
else:
    print('File already exists. Copy aborted.')

8. Advanced Techniques: Copying Only Specific File Types

You can use the glob module to selectively copy specific file types, such as .txt or .csv files.

import shutil
import glob

# Copy all .txt files
for file in glob.glob('data/*.txt'):
    shutil.copy(file, 'backup/')

This script copies all .txt files from the data folder to the backup folder.

9. Error Handling and Exception Handling

Handling potential errors during file operations is crucial. For example, errors may occur due to missing files or permission issues.

Adding Basic Exception Handling

import shutil

try:
    shutil.copy('non_existent_file.txt', 'backup/')
except FileNotFoundError as e:
    print(f'File not found: {e}')
except PermissionError as e:
    print(f'Permission error: {e}')
except Exception as e:
    print(f'An unexpected error occurred: {e}')

This script catches specific errors and handles them accordingly.

10. Conclusion

Using Python’s shutil module, you can efficiently copy files and directories. By incorporating techniques to prevent overwriting, selectively copying specific files, and adding error handling, you can make file operations safer and more effective. Try implementing these methods in your daily projects to streamline file management tasks with Python.