Why Does shutil.copytree() and distutils.dir_util.copy_tree() Copy the Contents of a Source Directory, Not the Directory Itself?

Are you trying to copy a directory and its contents using Python’s shutil or distutils modules, but ending up with only the contents being copied, not the directory itself? You’re not alone! This confusion has plagued many a Python developer, and in this article, we’ll dive into the reasons behind this behavior and provide clarity on how to achieve your desired outcome.

The Problem: shutil.copytree() and distutils.dir_util.copy_tree() Copying Contents, Not the Directory

Let’s start with an example. Suppose you have a directory structure like this:

Source/
    file1.txt
    file2.txt
    subdirectory/
        file3.txt

And you want to copy the entire “Source” directory, including all its contents, to a new location using shutil.copytree() or distutils.dir_util.copy_tree(). You might expect the following code to achieve this:

import shutil

shutil.copytree('Source', 'Destination')

Or:

from distutils.dir_util import copy_tree

copy_tree('Source', 'Destination')

However, when you run this code, you’ll find that only the contents of the “Source” directory are copied to the “Destination” directory, not the directory itself. Instead of getting:

Destination/
    Source/
        file1.txt
        file2.txt
        subdirectory/
            file3.txt

You’re left with:

Destination/
    file1.txt
    file2.txt
    subdirectory/
        file3.txt

This can be frustrating, especially if you need to preserve the original directory structure.

Why Does This Happen?

The reason for this behavior lies in the documentation of both shutil.copytree() and distutils.dir_util.copy_tree(). According to the official Python documentation:

“The destination location must not already exist. If the destination already exists and is a directory, it must be empty.”

In other words, both functions assume that the destination directory already exists, and they will only copy the contents of the source directory into it. If the destination directory doesn’t exist, they will create it, but only to hold the copied contents, not to replicate the source directory itself.

Solving the Problem: Copying the Directory and Its Contents

So, how do you copy the entire directory, including its contents, using shutil or distutils? There are a few workarounds:

Method 1: Using os.mkdir() to Create the Destination Directory

One way is to create the destination directory manually using os.mkdir(), and then use shutil.copytree() or distutils.dir_util.copy_tree() to copy the contents:

import os
import shutil

os.mkdir('Destination/Source')
shutil.copytree('Source', 'Destination/Source')

Or:

import os
from distutils.dir_util import copy_tree

os.mkdir('Destination/Source')
copy_tree('Source', 'Destination/Source')

This approach ensures that the destination directory is created, and then the contents of the source directory are copied into it.

Method 2: Using shutil.copmtree() with the dirs_exist_ok Argument (Python 3.8+)

In Python 3.8 and later, shutil.copytree() has an additional argument called dirs_exist_ok. By setting this to True, you can instruct copytree() to create the destination directory and copy the contents into it:

import shutil

shutil.copytree('Source', 'Destination/Source', dirs_exist_ok=True)

This method is more concise and convenient than the first one, but it’s only available in Python 3.8 and later.

Method 3: Using distutils.dir_util.copy_tree() with the preserve_mode Argument

distutils.dir_util.copy_tree() has a preserve_mode argument that, when set to 1, will preserve the directory structure, including the source directory itself:

from distutils.dir_util import copy_tree

copy_tree('Source', 'Destination', preserve_mode=1)

This method will create the destination directory and copy the contents, preserving the original directory structure.

Conclusion

In conclusion, shutil.copytree() and distutils.dir_util.copy_tree() copy the contents of a source directory, not the directory itself, because they assume the destination directory already exists or will be created to hold the copied contents. To copy the entire directory, including its contents, you need to use one of the workarounds discussed in this article.

Remember to choose the method that best suits your needs, depending on your Python version and specific use case. By understanding the behavior of these functions and applying the right approach, you’ll be able to achieve your goal of copying directories and their contents with ease.

Method	Python Version	Code
Using os.mkdir()	2.7+	os.mkdir(‘Destination/Source’); shutil.copytree(‘Source’, ‘Destination/Source’)
Using shutil.copytree() with dirs_exist_ok	3.8+	shutil.copytree(‘Source’, ‘Destination/Source’, dirs_exist_ok=True)
Using distutils.dir_util.copy_tree() with preserve_mode	2.7+	copy_tree(‘Source’, ‘Destination’, preserve_mode=1)

Hope this article helped clarify the behavior of shutil.copytree() and distutils.dir_util.copy_tree() for you! If you have any questions or need further assistance, feel free to ask.

Frequently Asked Question

Get answers to the most pressing question about shutil.copytree() and distutils.dir_util.copy_tree()