python shutil

# Python shutil：文件操作中的瑞士军刀

它到底是什么

shutil这个模块，名字是shell utilities的缩写，听起来很正式，但干的事儿其实特别接地气。在日常开发中，我们经常要和文件打交道——复制、移动、删除、打包，这些操作用Python内置的open()配合os模块也能做，但写起来总觉得有点别扭。比如复制一个文件，你得先打开源文件读取内容，再创建目标文件写入，还得处理各种异常情况。shutil就是来解决这个问题的，它把操作系统级别的文件操作封装成了一个个函数，让我们不用关心底层的读写细节。

这套工具的设计理念很有意思：它不追求覆盖所有场景，而是专注于那些在命令行里经常用到、在代码里又特别容易出错的操作。比如复制整个目录树，如果用os模块自己去遍历递归，代码会变得又长又容易漏掉权限、符号链接这些细节。shutil把这些麻烦事都打包好了。

它能做什么

shutil的能力范围其实比多数人想象的要广。除了最基本的文件复制，它还能干几件挺特别的事：

文件归档这块值得好好说说。shutil支持创建和解压zip、tar、gztar、bztar、xztar这些格式的归档文件。这在实际项目中特别有用，比如你需要把用户上传的一组文件打包下载，或者定时备份数据库导出文件到压缩包。它的实现方式也很有意思，不是简单地调用系统命令，而是通过Python内置的zipfile和tarfile模块来实现的，所以跨平台表现很一致。

另一个容易被忽略的功能是磁盘空间查询。shutil.disk_usage()能返回目录所在磁盘的总空间、已用空间和可用空间，这在做文件上传服务时特别实用——总不能等到磁盘写满了再报错吧。

还有一点，shutil的移动操作其实是跨文件系统的。这就意味着你可以在同一台机器上把文件从一个磁盘分区移动到另一个，它内部会智能判断：如果在同一个文件系统里，就用os.rename()直接修改目录项；如果不是，就复制过去再删除原文件。这个细节决定了你的移动目录操作不会在跨分区时莫名其妙报错。

实际怎么用

代码这部分说几个常见场景，每个场景都不复杂但很实用。

文件复制本身就有好几个层次：

importshutilimportos# 复制文件内容，但不保留元数据shutil.copyfile('source.txt','dest.txt')# 复制文件并保留权限等元数据shutil.copy2('source.txt','dest.txt')# 复制整个目录树，目标目录不能事先存在shutil.copytree('src_dir','dst_dir')# 复制目录时忽略特定文件defignore_pyc_files(dirname,filenames):return[fforfinfilenamesiff.endswith('.pyc')]shutil.copytree('src','dst',ignore=ignore_pyc_files)

这里有个小坑值得注意：copytree的dst参数指定的目录绝对不能是已存在的，否则会报FileExistsError。这让很多人第一次用时都愣了一下。解决方案是在调用前先检查一下目标是否存在，或者用os.path.exists()判断后先删除。

文件移动和删除：

# 移动文件或目录shutil.move('old_location','new_location')# 递归删除目录及其内容shutil.rmtree('some_dir')

rmtree这个函数要格外小心，它没有回收站的概念，删了就没了。很多新手在测试环境里随便用它删目录，结果不小心把参数传错了，整个项目目录被删掉。所以实际项目里往往会在调用rmtree前加一层确认机制，或者至少打日志记录下来。

归档操作：

# 创建归档文件shutil.make_archive('backup','zip','my_directory')# 解压归档shutil.unpack_archive('backup.zip','extract_dir')

make_archive返回的是生成的文件路径，这个返回值有时候容易被忽略。另外它不支持增量归档，每次都是全量打包，如果数据量很大，就需要考虑用其他方案了。

一些实践中的讲究

用shutil这么多年，有些经验是踩坑踩出来的：

第一个是权限问题。shutil.copy2理论上会保留文件的元数据，包括权限、修改时间等，但在Windows上有些特殊属性可能保留不了。而copytree有个参数叫symlinks，默认是False，意思是如果源目录里有符号链接，它不会复制链接本身，而是复制链接指向的内容。如果希望保留符号链接本身，得明确设置symlinks=True。

第二个是异常处理。shutil的函数抛出异常的场景很多，比如目标路径不可写、磁盘空间不足、权限不够。一个比较健壮的写法是先检查再操作，而不是等异常抛出再处理：

importshutilimportosimporterrnodefsafe_copy(src,dst):ifnotos.path.exists(src):raiseFileNotFoundError(f"源文件不存在:{src}")dst_dir=os.path.dirname(dst)ifdst_dirandnotos.path.exists(dst_dir):os.makedirs(dst_dir)try:shutil.copy2(src,dst)exceptPermissionError:# 这里可以记录日志，或者尝试其他方案print(f"权限不足，无法复制到{dst}")exceptOSErrorase:ife.errno==errno.ENOSPC:print("磁盘空间不足")

第三个是关于大数据量的场景。shutil在复制大文件时，内部用的是缓冲读取，缓冲区大小是16KB。对于几百MB甚至几GB的文件，这个缓冲区其实偏小了。如果需要提高大文件复制的效率，可以考虑自己实现一个带更大缓冲区的复制函数，当然这已经超出了shutil的范围。

和其他方案的对比

Python世界里处理文件操作还有其他选择，但定位都不太一样。

pathlib是Python 3.4引入的面向对象文件路径库。它和shutil的关系更像是一个补充而不是竞争。pathlib擅长路径操作——拼接、解析、判断类型，而shutil专门处理文件内容的复制移动。比如你要复制文件，pathlib只提供了Path.open()，复制逻辑还得自己写。所以实践中经常是两者搭配使用：用pathlib来操作路径，用shutil来做具体操作。

os模块是比shutil更底层的存在。os.rename可以重命名文件，但跨文件系统就得报错；os.remove只能删单个文件；os.walk可以遍历目录树。实际上shutil的很多实现底层就是在调用os模块的函数，只是加上了一些异常处理和智能判断。比如shutil.move的代码里，就有这么一段：

ifos.path.isdir(src):ifos.path.exists(dst):...else:shutil.copy2(src,dst)os.unlink(src)

所以如果只是简单的文件重命名，用os.rename就够了；但要处理复杂的移动场景，shutil更省心。

第三方库像send2trash，它可以实现把文件移到回收站而不是直接删除，这在图形界面应用里很实用，但它的作用范围窄，只解决一个特定问题。还有一个叫distutils.dir_util的，提供了copy_tree等方法，但distutils在Python 3.12里已经被标记为弃用，不建议在新项目里用。

最近几年出现了一些关注文件监控和同步的库，比如watchdog，它的定位是实时监控文件系统变化并触发事件，和shutil是完全不同的方向。shutil是主动操作，watchdog是被动监听。

如果说要给个选择建议，大概是这样的：如果你是写脚本处理一次性的文件操作，shutil够用了；如果你在开发一个需要频繁操作文件的应用，可以考虑把shutil的功能封装一下，加上日志、事务、回滚这些支持；如果是在维护一个遗留系统，可能会遇到用os模块写的文件操作代码，那可以把这些代码逐渐替换成shutil，能省不少调试时间。

shutil这个模块最妙的地方在于，它把那些看起来琐碎但又容易出错的系统级操作，包装成了几个简单直接的函数。用对了地方，代码会干净很多，也更容易维护。但也要记住，它毕竟只是对系统调用的封装，真正的错误处理、事务保证这些，还是得自己来。