shutil.copytree() 默认拒绝覆盖目标目录且不处理源为空的情况,因设计原则是只新建不覆盖;Python 3.8+ 可用 dirs_exist_ok=True 跳过目录存在检查,但文件冲突仍报错,强制覆盖需先 shutil.rmtree()。

直接用 shutil.copytree() 就行,但默认会报错——它拒绝覆盖目标目录,也不处理源目录为空的情况。
为什么 copytree() 默认失败?
常见错误是调用 shutil.copytree("src", "dst") 时遇到 FileExistsError: [Errno 17] File exists。这不是因为文件冲突,而是因为目标路径 "dst" 已存在(哪怕只是个空文件夹)。copytree() 的设计原则很明确:不覆盖、不追加、只新建。
- 源目录为空?
copytree()仍会复制(生成空目标目录),没问题 - 目标目录已存在?直接抛
FileExistsError,不管它是不是空的 - 想“覆盖复制”?必须手动删目标或改用其他策略
安全覆盖非空目标目录的写法
最稳妥的做法是先判断并清理目标路径,再调用 copytree():
import shutil
import os
def copytree_force(src, dst):
if os.path.exists(dst):
shutil.rmtree(dst)
shutil.copytree(src, dst)
copytree_force("my_project", "backup/my_project")
注意:shutil.rmtree() 会无条件删除整个 dst 树,包括非空目录,所以它天然适配“递归复制非空目录树”的需求。别用 os.rmdir() —— 它只删空目录,遇到非空就报 OSError。
立即学习“Python免费学习笔记(深入)”;
Python 3.8+ 可用 dirs_exist_ok=True
如果你用的是 Python ≥ 3.8,shutil.copytree() 增加了 dirs_exist_ok 参数,能绕过“目标已存在”错误:
shutil.copytree("src", "dst", dirs_exist_ok=True)
但它不会覆盖同名文件——遇到已存在的文件会报 FileExistsError。也就是说,它只跳过目录存在检查,不处理文件级冲突。真正要“强制覆盖”,还是得靠先 rmtree()。
另外,dirs_exist_ok=True 对空源目录依然有效,无需额外判断。
真正容易被忽略的是权限和符号链接行为:copytree() 默认不复制文件权限(Linux/macOS 下可能丢 chmod 信息),也不解析软链接(而是原样复制链接本身)。如果项目依赖精确权限或需要展开链接,得显式传 copy_function=shutil.copy2 或用 symlinks=True 参数。


















