Repository navigation
Support exist_ok for pathlib's Path.copy_into() #143052
Description
Bug report
Bug description:
Background
The Path.copy_into() method (introduced in Python 3.14) is used to copy files or directories into another directory.
The behaviour of files being copied and directories being copied is inconsistent when the destination directory contains a file or directory with the same name.
Examples
When a file is copied into a directory that already has a file with that name, the copied file overwrites the file at the destination directory:
"""
# Copying a file into a directory that already has a file with the same name #
Directory Structure:
dir_a
|__my_file.txt
dir_b
|__my_file.txt
"""
from pathlib import Path
dir_a_my_file = Path("dir_a") / "my_file.txt"
dir_b = Path("dir_b")
# Act
dir_a_my_file.copy_into(dir_b) # Success - dir_a/my_file.txt overwrites dir_b/my_file.txtHowever, when a directory is copied into another directory (one which contains a sub-directory with the same name),
the copy operation fails and FileExistsError is raised:
"""
# Copying a directory into a directory, that contains a sub-directory with the same name #
Directory Structure:
dir_a
|__my_dir
dir_b
|__my_dir
"""
from pathlib import Path
dir_a_my_dir = Path("dir_a") / "my_dir"
dir_b = Path("dir_b")
# Act
dir_a_my_dir.copy_into(dir_b) # Failure - FileExistsError is raised.Problem
The behaviour of the copy_into() method in the file case (success) and in the directory case (failure) is inconsistent.
It is also inconsistent with how Linux (when using cp -r) handles this exact same case.
Expected Result
Instead of raising an exception, the copied directory should be merged with the existing one.
Fix Suggestion
-
Add a default
exist_ok=Trueparameter tocopy_into().
This parameter is already used in thePath.touch()andPath.mkdir()methods, and should be familiar to users. -
When a file is copied into a destination directory that already has a file with the same name:
-
If
exist_ok=True, the copied file should overwrite the file at the destination directory.
This is the already the current behaviour, so no additional changes are required. -
If
exist_ok=False, aFileExistsErrorexception will be raised. This is consistent with the behaviour ofPath.touch().
-
-
When a directory is copied into a destination directory that contains a sub-directory with the same name:
- If
exist_ok=True, the copied directory will be merged with the destination's sub-directory.
This is consistent with the behaviour of copying in Linux. - If
exist_ok=False, aFileExistsErrorexception will be raised. This is consistent with the behaviour ofPath.mkdir().
- If
Thank you.
CPython versions tested on:
3.14
Operating systems tested on:
Linux
Activity
[-]Inconsistent behaviour in `pathlib.Path.copy_into()` when copying files vs. copying directories[/-][+]Inconsistent behaviour in `pathlib`'s `Path.copy_into()` when copying files vs. copying directories[/+]pythongh-143052: add exist_ok in copy_info func, allow merge same dir
pythongh-143052: add exist_ok in copy_info func, allow merge same dir
picnixz commentedon Dec 24, 2025
What is the behavior of Path.copy()? I believe we should align copy_into(). Note that the default behavior is the same as of shutil.copytree() which raises such errors on existing directories so I do not think it is a bug.
[-]Inconsistent behaviour in `pathlib`'s `Path.copy_into()` when copying files vs. copying directories[/-][+]Support `exist_ok` for `pathlib`'s `Path.copy_into()`[/+]picnixz commentedon Dec 24, 2025
Now for more advanced usages such as this feature request, I believe shutil.copytree should be preferred then. We sometimes have APIs that are more restrictive because generic ones exist elsewhere.
cc @barneygale
0x6e6174 commentedon Dec 31, 2025
I find the it confusing that
Path.mkdir()accepts anexists_okargument, butPath.copy()andPath.copy_into()do not. I think that allowing said methods to overwrite existing files is a feature that makes sense to implement, because otherwise one would have to remove the target directory prior to copying or defer to something outside of pathlib.picnixz commentedon Dec 31, 2025
I think the reason why
mkdiracceptsexists_okis becauseos.makedirsdoes (but notos.mkdir) and that creating a directory is usually harmless but copying something into a directory that may already exist and overwriting stuff is not harmless.I looks like it was a deliberate choice (see #73991 (comment)) where we restricted the interface. Since it was explicitly asked to open a https://discuss.python.org/c/ideas/6 thread to discuss improvements, that's what we should do.
Note: I personally don't care about which design we choose but I do care about maintenance burden (the implementation doesn't look trivial to me as it seems to assume that we won't encounter existing directories), which is why I'm leaving it to Barney. He may also decide whether this should be considered a bug or not (maybe it is!)