Shutil module in Python

The standard library in Python includes various modules for working with files. In this article we will explore one such module known as shutil, this module is normally used for performing high level file operations such as copying or moving files and even entire directories.

The module includes various functions for performing the various file-related operations. In the following section we will explore the functions and their usage.

Copy Files

copyfile() 

The copyfile() function takes in two arguments, the source and the destination. It copies the contents of the source to the destination file.

copyfile(src, dst)

If successful, the function returns the name of the destination file. It raises an IOError if it is unable to write to the destination file for example due to lack of write permissions.

import shutil

shutil.copyfile("myfile.py", "myfile.py.copy")

In the above example, we assumed we have a file named 'myfile.py', the function will create a new file called "myfile.py.copy" with the contents of the existing file. If a file exists with the name of the destination file, its contents will be overwritten.

copy()

With the copy() function, the destination can be a directory, in which case a new file with the same name as the original file will be created in the directory given. If the source and the destination refers to the same file, a SameFileError exception will be raised.

copy(src, dst)

The function returns the destination file/folder. 

from shutil import copy
copy('john.png', 'images')

In the above example, a new file named "john.png" will be copied inside the "images" directory.

copy2()

The previous functions only copies the source file's contents but does not copy its metadata to the destination file. we can use the copy2() function  if we want the copy file to share same characteristics with the original file. Such characteristics includes, the date of creation, last modified and last accessed dates.

The copy2() function works exactly like the copy() function except that it as well copies the metadata of the source file to the destination file.

copy2(src, dst)

from shutil import copy2

copy2('mozart.mp3', 'music')

In the above example, a new file named "mozart.mp3" will be copied in the music directory with the contents of the source file. It will contain same metadata as the source file.

Manipulating directory trees

The shutil module also includes functions for working with entire directory trees rather than individual files.

copytree()

This function is used to copy an entire directory into a destination directory. It recursively copies files from the source directory into the destination directory.

copytree(src, dst, ...)

The function returns the path of the destination directory.

# importing shutil module  
import shutil  
  
src = r'D:\project\pynerds'  
dest = r'D:\project\NewFolder'  
  
# Copy the content of  source to destination  
shutil.copytree(src, dest)  

You can also specify other arguments such as the files to ignore, the function used for copying e.t.c

rmtree() 

This function can be used to delete a directory with its contents.

rmtree(path, ignore_errors = False, ...)

The path parameter specifies the path to the directory to be removed. If the ignore_errors parameters is set to True, any errors encountered are ignored.

move()

This function can be used to recursively move a directory and its contents from one location to another. Its works similarly to the UNIX command mv .

move(src, dst, copy_function=<function copy2 at 0x000001C13E1C58A0>)

The optional copy_function parameter can be used to specify the function that will be used for copying the files. By default, the copy2() function is used, if necessary, you can specify a similar function such as copy() or copyfile().

#import the shutil module
import shutil

#move a directory
shutil.move('project', 'NewFolder')