用 tarfile.open() 创建 .tar.gz 文件必须指定 'w:gz' 模式，否则生成无压缩假包；路径含中文需 os.fsencode() 处理；add() 推荐显式设 arcname；extractall() 默认不还原权限，需 filter='data' 或手动设 mode；不支持加密/分卷，仅 gzip/bzip2/lzma 压缩。

用 tarfile.open() 创建 .tar.gz 文件时必须指定 'w:gz' 模式

默认的 'w' 模式只生成未压缩的 .tar，不加 :gz 后缀就压不出 .gz。Python 的 tarfile 把压缩格式和打开模式强绑定，不是靠文件扩展名自动识别的。

常见错误是写成 tarfile.open('out.tar.gz', 'w') —— 这会生成一个无压缩、但后缀带 .gz 的假包，解压时会报 OSError: Invalid gzip data。

• 正确写法：tarfile.open('archive.tar.gz', 'w:gz')
• 路径中的中文或特殊字符需提前用 os.fsencode() 处理，否则在某些系统上会 UnicodeEncodeError
• 添加文件时推荐用 add(file_path, arcname=...) 显式控制归档内路径，避免绝对路径被完整保留（比如 /home/user/file.txt 会变成归档里的冗余全路径）

解压 .tar.gz 时 extractall() 默认不校验文件权限和所有者

Linux/macOS 下用 tar -xzf 解压会还原 chmod 和 chown 信息，但 Python tarfile 默认忽略这些元数据，尤其对脚本或可执行文件容易导致“Permission denied”。

Claw Code Suite (Python-Only Edition)

仅使用 Python 将 Claw Code 虚拟化框架与 OpenClaw 集成，提供 184 种工具和 200 多条命令，用于安全分析和代码质量...

下载

• 加参数 numeric_owner=True 可跳过用户/组名解析失败问题（避免因目标系统缺对应 UID/GID 而报错）
• 要还原权限，必须传 filter='data'（Python 3.12+）或手动遍历 tarinfo 设置 tarinfo.mode 再调用 extract()
• extractall(path='.', members=None) 中的 members 可用于白名单过滤，比如只解压 .py 和 .json 文件，防恶意路径遍历（../../etc/passwd）

tarfile 不支持分卷压缩或加密，别指望它替代 7z 或 zip -e

如果需求里有“密码保护”“自动分卷”“跨平台高压缩率”，tarfile 直接不满足。它只是 POSIX tar 格式的忠实实现，仅支持 gzip/bzip2/lzma 三种压缩方式，且都不带加密。

立即学习“Python免费学习笔记（深入）”；

• gzip 压缩率最低但最快，适合频繁读写的日志归档
• bzip2（用 'w:bz2'）压缩率高但 CPU 消耗大，小文件场景可能反而更慢
• lzma（'w:xz'）压缩率最高，但 Python 3.3+ 才稳定支持，旧环境会 ImportError
• 想加密码？只能外包给系统命令：subprocess.run(['7z', 'a', '-psecret', 'out.7z', 'data/'])

大文件打包时内存暴增，得用 add() 配合 filter 控制内容

tarfile.add() 默认递归扫描整个目录树并一次性载入所有文件元数据，遇到含数万小文件的目录，很容易 OOM 或卡死。

• 用 filter 参数回调函数提前过滤掉不需要的文件（比如 *.tmp、__pycache__）
• 对超大单文件（>1GB），改用 addfile() + open(..., 'rb') 流式写入，避免 add() 内部的 os.stat() 和缓冲区拷贝
• 别依赖 getnames() 获取全部文件列表再处理——它会强制加载整个 tar header，大包下很慢

注意：tarfile 对硬链接、设备文件、socket 文件等特殊 inode 类型支持有限，生产环境打包前最好先 find /path -type f 确认目标全是普通文件