Python py7zr 库用于处理 7z 压缩文件，支持创建、解压、加密、分卷等功能。API 简洁，支持中文路径。内容涵盖安装、基础解压、密码处理、部分文件解压、中文路径处理、创建压缩文件、压缩级别设置、加密压缩包、分卷压缩、查看信息、更新压缩包及批量处理工具实现。包含常见问题解决方案。
在日常开发中，我们经常需要处理各种压缩文件，而 7z 格式以其高压缩率深受青睐。如果你用 Python 处理 7z 文件，可能会遇到这些问题：找不到合适的库、API 繁琐、解压中文路径乱码……py7zr 库的出现，有效解决了这些问题。
py7zr 是 Python 中最流行的 7z 文件处理库，支持创建、解压 7z 文件，还能处理密码保护、分卷压缩等高级功能，API 简洁易用。本文将从基础到进阶，通过示例掌握 py7zr 的核心用法，让 7z 文件处理变得简单高效。
在介绍用法前，先看看 py7zr 的核心优势：
with 语句实现上下文管理，自动处理资源释放；pycryptodome（可选，用于加密功能），安装方便。相比其他库（如 pylzma 需要手动处理细节），py7zr 更贴近'开箱即用'的需求。
py7zr 是第三方库，安装非常简单，直接用 pip：
# 基础安装（支持基本压缩/解压，无加密）
pip install py7zr
# 完整安装（支持加密功能，需安装 pycryptodome）
pip install py7zr[full]
验证安装是否成功：
import py7zr
print(py7zr.__version__) # 输出当前版本，如 0.21.0（确保≥0.18.0，功能更稳定）
解压是最常用的操作，py7zr 通过 py7zr.SevenZipFile 类实现，配合 with 语句自动管理文件流，非常安全。
最简单的场景：将 test.7z 解压到 output_dir 目录（不存在会自动创建）。
import py7zr
# 解压无密码的 7z 文件
with py7zr.SevenZipFile("test.7z", mode="r") as z:
# mode="r"表示读取
z.extractall(path="output_dir") # 解压到指定目录
print("解压完成！")
代码说明：
mode="r"：表示打开文件用于读取（解压）；extractall(path)：将所有内容解压到 path 目录，目录不存在时自动创建；with 语句确保压缩文件用完后自动关闭，避免资源泄露。如果 7z 文件设置了密码，只需在打开时传入 password 参数：
import py7zr
# 解压带密码的 7z 文件（需安装 py7zr[full]）
with py7zr.SevenZipFile("encrypted.7z", mode="r", password="mypass123") as z:
z.extractall("encrypted_output")
print("带密码的文件解压完成！")
注意：密码功能依赖 pycryptodome 库，若未安装会报错，需执行 pip install py7zr[full]。
有时不需要解压全部文件，可通过 extract() 方法指定要解压的文件：
import py7zr
with py7zr.SevenZipFile("test.7z", mode="r") as z:
# 获取压缩包内所有文件列表
all_files = z.getnames()
print("压缩包内所有文件：", all_files)
# 筛选出.txt 文件
txt_files = [f for f in all_files if f.endswith(".txt")]
print("要解压的 txt 文件：", txt_files)
# 只解压筛选出的文件
z.extract(path="txt_output", targets=txt_files)
print("部分文件解压完成！")
关键方法：
getnames()：返回压缩包内所有文件的路径列表；extract(targets=列表)：仅解压 targets 中指定的文件。py7zr 默认支持 UTF-8 编码，对中文路径友好，无需额外配置。如果遇到特殊编码，可通过 encoding 参数指定：
import py7zr
# 解压含中文路径的 7z 文件（默认 UTF-8，如需其他编码可指定）
with py7zr.SevenZipFile("中文文件.7z", mode="r", encoding="utf-8") as z:
z.extractall("中文输出目录")
print("中文路径文件解压完成！")
提示：7z 格式本身使用 UTF-8 存储文件名，一般无需修改 encoding 参数，直接解压即可。
除了解压，py7zr 还能创建 7z 文件，支持添加单个文件、目录、设置压缩级别、加密等功能。
将 file.txt 或 docs 目录压缩为 archive.7z：
import py7zr
# 压缩单个文件
with py7zr.SevenZipFile("archive.7z", mode="w") as z:
# mode="w"表示写入（创建）
z.write("file.txt") # 添加单个文件
# 压缩目录（会包含目录下所有文件和子目录）
with py7zr.SevenZipFile("docs_archive.7z", mode="w") as z:
z.writeall("docs", arcname="documents") # arcname：压缩包内的目录名（可选）
方法区别：
write(file_path)：添加单个文件，压缩包内路径与原路径一致；writeall(dir_path, arcname)：添加整个目录，arcname 可指定在压缩包内的目录名（如将 docs 压缩为 documents 目录）。7z 支持不同压缩级别（0-9，级别越高压缩率越高但速度越慢），默认级别为 5。可通过 compression_level 参数设置：
import py7zr
# 压缩多个文件，设置最高压缩级别（9）
with py7zr.SevenZipFile(
"multi_files.7z",
mode="w",
compression_level=9 # 0=最快，9=最高压缩率
) as z:
z.write("a.txt")
z.write("b.jpg")
z.write("data/") # 添加目录
print("多文件压缩完成（最高级别）！")
通过 password 参数为压缩包设置密码，保护敏感文件：
import py7zr
# 创建带密码的加密压缩包（需安装 py7zr[full]）
with py7zr.SevenZipFile(
"protected.7z",
mode="w",
password="secret123", # 密码
compression_level=5
) as z:
z.writeall("sensitive_data/")
print("加密压缩包创建完成！")
安全提示：密码会以明文形式传入，实际项目中建议从环境变量或密钥管理服务获取密码。
当压缩包过大时（如超过 1GB），可分卷存储（如每个分卷 100MB），通过 volume 参数指定分卷大小（单位：字节）：
import py7zr
# 创建分卷压缩文件（每个分卷 100MB）
VOLUME_SIZE = 100 * 1024 * 1024 # 100MB = 100*1024*1024 字节
with py7zr.SevenZipFile(
"large_archive.7z",
mode="w",
volume=VOLUME_SIZE # 分卷大小
) as z:
z.writeall("large_files/") # 压缩大目录
print("分卷压缩完成！")
分卷文件会自动命名为 large_archive.7z.001、large_archive.7z.002……解压时只需指定第一个分卷（.001），py7zr 会自动识别后续分卷。
py7zr 还支持查看压缩包内文件信息、添加新文件到已有压缩包等高级操作。
获取压缩包内文件的名称、大小、修改时间等信息：
import py7zr
with py7zr.SevenZipFile("test.7z", mode="r") as z:
# 获取压缩包元数据（含所有文件信息）
info = z.list()
print("压缩包信息：")
for file_info in info:
print(f"文件名：{file_info.filename}")
print(f"原始大小：{file_info.uncompressed}字节")
print(f"压缩后大小：{file_info.compressed}字节")
print(f"修改时间：{file_info.mtime}")
print("---")
返回字段说明：
filename：文件路径；uncompressed：原始大小（字节）；compressed：压缩后大小（字节）；mtime：最后修改时间。通过 mode="a"（追加模式）向现有 7z 文件添加新文件：
import py7zr
# 向已有压缩包添加新文件
with py7zr.SevenZipFile("existing.7z", mode="a") as z:
# mode="a"表示追加
z.write("new_file.txt")
z.write("new_dir/")
print("压缩包更新完成！")
注意：追加模式仅支持添加新文件，不支持删除或修改已有文件（7z 格式本身限制）。
结合前面的知识点，我们实现一个实用的 7z 文件批量处理工具，支持：
import os
import py7zr
from pathlib import Path
# 用 pathlib 处理路径更优雅
def batch_extract_7z(
source_dir, # 存放 7z 文件的目录
output_root, # 解压根目录
password_dict=None # 密码字典（用于尝试加密文件）
):
"""批量解压目录下的所有 7z 文件"""
# 确保输出目录存在
Path(output_root).mkdir(parents=True, exist_ok=True)
# 遍历 source_dir 下的所有.7z 文件
for filename in os.listdir(source_dir):
if filename.endswith(".7z"):
# 构建完整路径
zip_path = os.path.join(source_dir, filename)
# 解压目录：output_root/文件名（不含.7z）
extract_dir = os.path.join(output_root, Path(filename).stem)
Path(extract_dir).mkdir(exist_ok=True)
print(f"开始解压：{filename} → {extract_dir}")
try:
# 尝试无密码解压
with py7zr.SevenZipFile(zip_path, mode="r") as z:
z.extractall(extract_dir)
print(f"✅ 解压成功（无密码）：{filename}")
except py7zr.exceptions.Bad7zFile:
print(f"❌ 错误：{filename}不是有效的 7z 文件")
except py7zr.exceptions.PasswordRequired:
# 若需要密码，尝试密码字典
if not password_dict:
print(f"❌ 错误：{filename}需要密码，但未提供密码字典")
continue
# 遍历密码字典尝试
success = False
for pwd in password_dict:
try:
with py7zr.SevenZipFile(zip_path, mode="r", password=pwd) as z:
z.extractall(extract_dir)
print(f"✅ 解压成功（密码：{pwd}）：{filename}")
success = True
break
except:
continue
if not success:
print(f"❌ 错误：{filename}密码不正确，已尝试所有密码")
except Exception as e:
print(f"❌ 解压失败：{filename}，错误：{str(e)}")
# 示例用法
if __name__ == "__main__":
# 配置参数
SOURCE_DIR = "7z_files" # 存放 7z 文件的目录
OUTPUT_ROOT = "7z_extracted" # 解压根目录
PASSWORD_DICT = ["123456", "password", "admin"] # 常用密码字典
# 批量解压
batch_extract_7z(SOURCE_DIR, OUTPUT_ROOT, PASSWORD_DICT)
使用说明：
7z_files 目录；7z_extracted 目录下创建以文件名命名的子目录，存放解压内容；PASSWORD_DICT 中的密码，成功则解压，失败则提示。在使用 py7zr 过程中，可能会遇到一些问题，这里总结了常见场景及解决方法：
password 参数，或通过密码字典尝试。解决：解压时指定 encoding="gbk" 参数：
with py7zr.SevenZipFile("中文.7z", mode="r", encoding="gbk") as z:
z.extractall()
.002），或路径错误；.001、.002…），解压时指定第一个分卷（.001）。with 语句 + 简洁 API，几行代码实现压缩/解压；如果你需要在 Python 中处理 7z 文件，py7zr 是常用库之一——它能让你摆脱繁琐的底层操作，专注于业务逻辑。无论是批量处理压缩包，还是构建带压缩功能的应用，py7zr 都能胜任。
pathlib.Path 替代 os.path 处理路径，代码更简洁；tqdm 库为解压/压缩过程添加进度条，提升用户体验；zipfile（处理 zip）、tarfile（处理 tar）库，实现多格式压缩文件统一处理。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online