Python shutil 模块常用函数与示例

shutil.copy(src, dst) & shutil.copy2(src, dst)

复制文件。copy只复制文件内容和权限，copy2在此基础上额外保留文件的元数据（访问/修改时间等）。

import shutil

# 只复制内容和权限
shutil.copy('data/source.txt', 'backup/source_copy.txt')

# 复制内容、权限并保留元数据
shutil.copy2('data/source.txt', 'backup/source_copy2.txt')

shutil.copyfile(src, dst) & shutil.copyfileobj(fsrc, fdst[, length])

copyfile进行二进制层面的文件复制，要求源文件必须是普通文件；copyfileobj接受已打开的文件对象，可用于部分复制或自定义缓冲区大小。

import shutil

# 直接复制文件（二进制拷贝）
shutil.copyfile('data/a.bin', 'data/b.bin')

# 使用文件对象拷贝（可指定 length）
with open('data/a.bin', 'rb') as fsrc, open('data/b.bin', 'wb') as fdst:
    shutil.copyfileobj(fsrc, fdst, length=1024*64)   # 每次拷贝 64KB

shutil.copymode(src, dst) & shutil.copystat(src, dst)

仅复制文件的权限信息（copymode）或完整的状态信息（权限、时间戳等，copystat）。

import shutil, os

src = 'data/original.txt'
dst = 'data/clone.txt'
shutil.copy(src, dst)               # 先复制内容
shutil.copymode(src, dst)           # 只复制权限
shutil.copystat(src, dst)           # 复制权限+时间戳等

shutil.copytree(src, dst, dirs_exist_ok=False, ignore=None)

递归复制整个目录树。dirs_exist_ok=True（Python 3.8+）允许目标目录已存在；ignore 可用于过滤不需要复制的文件。

import shutil, os

def ignore_pycache(dir, files):
    return [f for f in files if f == '__pycache__']

shutil.copytree('project_src', 'project_backup',
                ignore=ignore_pycache)   # 忽略 __pycache__ 目录

shutil.move(src, dst)

移动文件或目录，等价于系统的 mv。如果 dst 为已存在的目录，源会被移动进去；如果是文件路径，则会改名。

import shutil

# 移动文件并改名
shutil.move('temp/report.txt', 'archive/2025/report_2025.txt')

# 移动整个目录
shutil.move('old_project', 'archived_projects/old_project')

shutil.rmtree(path, ignore_errors=False, onerror=None)

递归删除目录及其所有内容。onerror 可用于处理只读文件等异常。

import shutil, os, stat

def on_rm_error(func, path, exc_info):
    # 清除只读属性后重试删除
    os.chmod(path, stat.S_IWRITE)
    func(path)

shutil.rmtree('temp_folder', onerror=on_rm_error)

shutil.make_archive(base_name, format, root_dir=None, base_dir=None, **kwargs)

创建压缩归档。format 支持 'zip'、'tar'、'gztar' 等。对应的解压函数是 shutil.unpack_archive。

import shutil

# 打包为 zip
shutil.make_archive('backup/project', 'zip', root_dir='project')

# 解压 zip 包
shutil.unpack_archive('backup/project.zip', extract_dir='project_restored')

shutil.disk_usage(path)

返回指定路径所在磁盘的总容量、已用空间和可用空间（字节）。

import shutil

total, used, free = shutil.disk_usage('/')
print(f"总容量: {total//(2**30)} GB")
print(f"已用:   {used//(2**30)} GB")
print(f"可用:   {free//(2**30)} GB")

shutil.get_archive_formats()

获取当前支持的压缩格式列表，可配合 make_archive 使用。

import shutil

print("支持的压缩格式:", shutil.get_archive_formats())
# 示例输出: [('zip', 'ZIP archive', shutil._make_zip_archive), ...]

shutil.chown(path, user=None, group=None)

在类 Unix 系统上修改文件或目录的所有者和所属组。Windows 不支持。

import shutil

# 将文件所有者改为 'alice'，组改为 'staff'
shutil.chown('data/report.txt', user='alice', group='staff')

帮助快速掌握 shutil 模块的核心功能与常见用法。

Python shutil 模块常用函数与示例