Pythonのzipfileの使い方|ZIPの作成・展開と圧縮・文字化け・安全な展開
Python で「フォルダーを ZIP にまとめて保存したい」「受け取った ZIP の中身を確かめてから展開したい」ときは、標準ライブラリの zipfile を使います。インストール不要ですが、指定しないと圧縮されない、フォルダー構造が思った形にならないといった落とし穴があります。
この記事では、Windows 11 の Python 3.12 で実際に動かした結果つきで、次のことを解説します(2026 年 10 月に確認)。
- ZipFile を with で開く理由と、書き込みモード “w”・”a”・”x” の違い
- ZIP_DEFLATED を指定しないと圧縮されないこと(ファイルサイズで比較)
- arcname で ZIP の中の名前を整える方法と、フォルダーごと圧縮する関数
- 展開せずに一覧を見る・中身を読む方法と、extractall・extract
- 「../」入りの危険な ZIP、日本語ファイル名の文字化け、壊れた ZIP の見分け方
コマンド(tar・Compress-Archive など)での圧縮・展開は「tar・zipで圧縮・展開する方法」で解説しています。この記事は Python のコードで ZIP を扱う方法に絞ります。
準備:練習用のファイルを作る
サンプルは、練習用の空のフォルダーに sample.py などの名前で保存し、PowerShell でそのフォルダーに移動してから py sample.py で実行します。まず次のコードで、圧縮の材料になる project フォルダーを作ります。
from pathlib import Path
base = Path("project")
(base / "src").mkdir(parents=True, exist_ok=True)
(base / "data").mkdir(parents=True, exist_ok=True)
(base / "README.md").write_text("# sample project\n", encoding="utf-8")
(base / "src" / "app.py").write_text('print("hello")\n', encoding="utf-8")
lines = ["date,item,price"]
for i in range(3000):
lines.append(f"2026-10-{i % 28 + 1:02d},item{i % 50:02d},{(i * 37) % 1000 + 100}")
(base / "data" / "sales.csv").write_text("\n".join(lines) + "\n", encoding="utf-8")
Windows では改行が CRLF になり、sales.csv は 69,317 バイトになりました。Path の使い方は「Pythonのpathlibの使い方」で説明しています。
ZIP を作る:with と書き込みモード
ZipFile は with で開く
ZIP ファイルは、最後に「中に何が入っているか」の目次(セントラルディレクトリ)を書き込んで完成します。公式ドキュメントにも「プログラムを終える前に close() を呼ばないと、必要な記録が書き込まれない」とあります。close() を呼ぶ前と後で、ZIP として認識されるかを比べました。
import zipfile
z = zipfile.ZipFile("noclose.zip", "w", compression=zipfile.ZIP_DEFLATED)
z.write("project/data/sales.csv")
print(zipfile.is_zipfile("noclose.zip"))
z.close()
print(zipfile.is_zipfile("noclose.zip"))
False
True
close() の前はまだ ZIP として不完全でした。with zipfile.ZipFile(...) as z: と書けば、ブロックを抜けるとき(途中でエラーが起きたときも)自動で close() されます。with の仕組みは「Pythonのwith文とは?」で解説しています。以降のコードはすべて with を使います。
“w”・”a”・”x” の違い
ZipFile の 2 つ目の引数(mode)で、読むのか書くのかを選びます。同じ modes.zip に対して 3 つのモードを順に試しました。
import zipfile
def show(label):
with zipfile.ZipFile("modes.zip") as z:
print(label, z.namelist())
with zipfile.ZipFile("modes.zip", "w", compression=zipfile.ZIP_DEFLATED) as z:
z.write("project/README.md")
show("w 1回目:")
with zipfile.ZipFile("modes.zip", "w", compression=zipfile.ZIP_DEFLATED) as z:
z.write("project/src/app.py")
show("w 2回目:")
with zipfile.ZipFile("modes.zip", "a", compression=zipfile.ZIP_DEFLATED) as z:
z.write("project/README.md")
show("a:")
try:
with zipfile.ZipFile("modes.zip", "x") as z:
z.write("project/README.md")
except FileExistsError as e:
print("x:", e)
w 1回目: ['project/README.md']
w 2回目: ['project/src/app.py']
a: ['project/src/app.py', 'project/README.md']
x: [Errno 17] File exists: 'modes.zip'
| mode | 意味 | 同じ名前の ZIP があるとき |
|---|---|---|
| “r”(省略時) | 読む | そのまま読む |
| “w” | 新しく書く | 確認なしで中身を消して作り直す |
| “a” | 追加する | 今の中身の後ろに足す(なければ新しく作る) |
| “x” | 新しく書く | FileExistsError で止まる |
“w” の 2 回目で README.md が消えたように、“w” は既存の ZIP を黙って上書きします。大事な ZIP を上書きしたくない処理では “x” を使い、FileExistsError を except で受けて別の名前にするなどの対応をします(例外の書き方は「Pythonの例外処理入門」を参照)。
ZIP_DEFLATED を指定しないと圧縮されない
公式ドキュメントのとおり、compression の既定値は ZIP_STORED(圧縮しない)です。69,317 バイトの sales.csv で比べました。
import zipfile
from pathlib import Path
with zipfile.ZipFile("stored.zip", "w") as z:
z.write("project/data/sales.csv")
with zipfile.ZipFile("deflated.zip", "w", compression=zipfile.ZIP_DEFLATED) as z:
z.write("project/data/sales.csv")
print(Path("project/data/sales.csv").stat().st_size)
print(Path("stored.zip").stat().st_size)
print(Path("deflated.zip").stat().st_size)
69317
69459
10543
指定しないと、ZIP は元のファイルより 142 バイト(名前などの管理情報の分)大きくなりました。ZIP_DEFLATED を付けると約 15% の 10,543 バイトです。ほかの指定では、compresslevel=1が 18,362、compresslevel=9 が 10,351、ZIP_BZIP2 が 5,274、ZIP_LZMA が 3,792 バイトでした。
BZIP2・LZMA はさらに小さくなりますが、展開する側が対応していないと開けません。PowerShell 5.1 の Expand-Archive では、2 つとも「The archive entry was compressed using an unsupported compression method.」というエラーになりました(Windows の tar.exe では展開できました)。人に渡す ZIP は ZIP_DEFLATED にしておくのが無難です。
arcname で ZIP の中の名前を整える
z.write(ファイル) で入れると、ZIP の中の名前は「渡したパスからドライブ名と先頭の区切りを取ったもの」になり、絶対パスなら階層がまるごと入ります。2 つ目の引数 arcname で中の名前を指定できます。
import zipfile
from pathlib import Path
src = Path("project/src/app.py").resolve()
with zipfile.ZipFile("arcname.zip", "w", compression=zipfile.ZIP_DEFLATED) as z:
z.write(src)
z.write(src, arcname="app.py")
z.write(src, arcname="backup/src/app.py")
with zipfile.ZipFile("arcname.zip") as z:
for name in z.namelist():
print(name)
Users/(ユーザー名)/…/project/src/app.py
app.py
backup/src/app.py
1 行目は実際には練習用フォルダーまでのパスがすべて入っていました(途中を省略)。展開すると深い階層が作られ、ユーザー名も相手に伝わります。区切りは Windows でも「/」で記録されるので、read() などに渡す名前も / で書きます。

フォルダーごと圧縮する関数(rglob と relative_to)
フォルダーの中のファイルを rglob(“*”) ですべて集め、relative_to() で基準のフォルダーからの相対パスにして arcname に渡すと、図 1 のように名前を整えられます。
import zipfile
from pathlib import Path
def zip_dir(src_dir, zip_path, include_root=True):
src = Path(src_dir)
base = src.parent if include_root else src
with zipfile.ZipFile(zip_path, "w", compression=zipfile.ZIP_DEFLATED) as z:
for p in sorted(src.rglob("*")):
if p.is_file():
z.write(p, arcname=p.relative_to(base).as_posix())
zip_dir("project", "mine.zip")
zip_dir("project", "mine_flat.zip", include_root=False)
for name in ("mine.zip", "mine_flat.zip"):
with zipfile.ZipFile(name) as z:
print(name, z.namelist())
mine.zip ['project/data/sales.csv', 'project/README.md', 'project/src/app.py']
mine_flat.zip ['data/sales.csv', 'README.md', 'src/app.py']
include_root=True なら展開すると project フォルダーができ、False なら中身が直接並びます。展開したときに散らばらないよう、人に渡す ZIP はフォルダー名から始めるのがおすすめです。
shutil.make_archive との比較
フォルダーを丸ごと ZIP にするなら shutil.make_archive が 1 行で済みます。root_dir は ZIP の一番上にするフォルダー、base_dir はその中のどこから入れるかです。
import shutil
import zipfile
shutil.make_archive("made", "zip", root_dir=".", base_dir="project")
shutil.make_archive("made_flat", "zip", root_dir="project")
for name in ("made.zip", "made_flat.zip"):
with zipfile.ZipFile(name) as z:
print(name, z.namelist())
made.zip ['project/', 'project/data/', 'project/src/', 'project/README.md', 'project/data/sales.csv', 'project/src/app.py']
made_flat.zip ['data/', 'src/', 'README.md', 'data/sales.csv', 'src/app.py']
| shutil.make_archive | zipfile で自作 | |
|---|---|---|
| 書く量 | 1 行 | 関数が必要 |
| 圧縮 | されていた(infolist で compress_type が 8=ZIP_DEFLATED) | compression の指定が必要 |
| フォルダーの項目(project/ など) | 入る | 上の関数では入らない |
| 除外(*.log を入れないなど) | できない | if で自由に選べる |
まるごと固めるなら make_archive、除外や名前の変更が必要なら zipfile、と使い分けます。
展開せずに中身を見る・読む
namelist と infolist
namelist() は名前の一覧、infolist() はファイルごとの詳しい情報(ZipInfo)の一覧を返します。file_size は元のサイズ、compress_size は圧縮後のサイズです。
import zipfile
with zipfile.ZipFile("made.zip") as z:
for info in z.infolist():
if info.is_dir():
continue
print(f"{info.filename:24} {info.file_size:>6} -> {info.compress_size:>6} {info.date_time}")
project/README.md 18 -> 20 (2026, 10, 23, 11, 2, 2)
project/data/sales.csv 69317 -> 10401 (2026, 10, 23, 11, 2, 2)
project/src/app.py 16 -> 18 (2026, 10, 23, 11, 2, 2)
小さいファイルは圧縮で逆に 2 バイト増えています。date_time は更新日時、is_dir() はフォルダーの項目かどうかです。
read と open で中身を読む
展開しなくても、read(名前) で中身を bytes として取り出せます。大きなファイルは open(名前) でファイルのように少しずつ読めます。open で得られるのはバイナリなので、文字列として 1 行ずつ読むには io.TextIOWrapper で包みます。
import io
import zipfile
with zipfile.ZipFile("made.zip") as z:
data = z.read("project/README.md")
print(data)
with z.open("project/data/sales.csv") as f:
text = io.TextIOWrapper(f, encoding="utf-8", newline="")
for i, line in enumerate(text):
print(repr(line))
if i == 2:
break
b'# sample project\r\n'
'date,item,price\r\n'
'2026-10-01,item00,100\r\n'
'2026-10-02,item01,137\r\n'
名前は ZIP の中の名前と大文字・小文字まで完全に一致させます。z.read("project/readme.md") と書くと KeyError: "There is no item named 'project/readme.md' in the archive" になりました。文字コードの指定の考え方は「Pythonのファイル読み書き」と同じです。
展開する:extractall と extract
extractall(展開先) ですべて、extract(名前, 展開先) で 1 つだけ展開します。展開先のフォルダーがなければ作られます。extract は作ったファイルのパスを返します。
import zipfile
from pathlib import Path
with zipfile.ZipFile("made.zip") as z:
z.extractall("out_all")
print(z.extract("project/src/app.py", "out_one"))
for p in sorted(Path("out_all").rglob("*.*")):
print(p)
out_one\project\src\app.py
out_all\project\data\sales.csv
out_all\project\README.md
out_all\project\src\app.py
注意点は、同じ名前のファイルがあると確認なしで上書きすることです。out_all/project/README.md を書き換えてからもう一度 extractall すると、中身は「# sample project」に戻りました。公式ドキュメントの「展開の落とし穴」にも、同じ ZIP を 2 回展開すると黙って上書きすると書かれています。作業中のフォルダーではなく、新しい空のフォルダーに展開するのが安全です。
危険な ZIP から身を守る
「../」入りの名前(Zip Slip)を Python はどう扱うか
ZIP の中の名前は、作る側が自由に決められます。../evil.txt のような名前をそのまま展開先とつなぐと、展開先の外にファイルが書き込まれてしまいます。この攻撃は Zip Slip(パストラバーサルの一種)と呼ばれます。

Python の公式ドキュメントによると、zipfile の extract・extractall は、名前が絶対パスならドライブ名や先頭の「/」を取り除き、名前の中の「..」の部分をすべて取り除いて展開します(Windows では : < > | ” ? * を _ に置き換えます)。実際に試すため、練習用フォルダーの奥に空のフォルダーを作り、その中で次の 2 つを実行しました。
import zipfile
with zipfile.ZipFile("slip.zip", "w") as z:
z.writestr("safe.txt", "safe")
z.writestr("../evil.txt", "evil")
z.writestr("../../evil2.txt", "evil2")
z.writestr("docs/../../evil3.txt", "evil3")
import zipfile
from pathlib import Path
with zipfile.ZipFile("slip.zip") as z:
for name in z.namelist():
print(name, "->", z.extract(name, "out"))
for p in sorted(Path(".").rglob("*.txt")):
print(p)
safe.txt -> out\safe.txt
../evil.txt -> out\evil.txt
../../evil2.txt -> out\evil2.txt
docs/../../evil3.txt -> out\docs\evil3.txt
out\docs\evil3.txt
out\evil.txt
out\evil2.txt
out\safe.txt
4 つとも out の中に作られ、Git Bash の find で親のフォルダーも探しましたが、外には何も書き出されていませんでした。ただし公式ドキュメントの extractall の警告は「信頼できない ZIP を事前に調べずに展開してはいけない」で、zipfile は外に出ないよう「試みる」という書き方です。名前が書き換わるため、out の中の別のファイルを上書きすることもありえます。
展開する前に中身を確かめる関数
受け取った ZIP は、展開する前に一覧を調べ、怪しいものがあれば展開しないようにします。次の関数は、ファイル数・展開後の合計サイズ・絶対パス・「..」を調べ、問題を文字列のリストで返します。上限の数字は用途に合わせて変えてください。
import zipfile
from pathlib import PurePosixPath, PureWindowsPath
MAX_FILES = 1000
MAX_TOTAL = 100 * 1024 * 1024 # 展開後の合計 100MB まで
def check_zip(zip_path):
problems = []
with zipfile.ZipFile(zip_path) as z:
infos = z.infolist()
if len(infos) > MAX_FILES:
problems.append(f"ファイル数が多すぎる: {len(infos)}")
total = sum(i.file_size for i in infos)
if total > MAX_TOTAL:
problems.append(f"展開後のサイズが大きすぎる: {total:,} バイト")
for i in infos:
name = i.filename
win = PureWindowsPath(name)
if name.startswith(("/", "\\")) or win.drive:
problems.append(f"絶対パス: {name}")
elif ".." in PurePosixPath(name.replace("\\", "/")).parts:
problems.append(f"「..」を含む: {name}")
return problems
for path in ("made.zip", "slip.zip", "abs.zip"):
print(path, check_zip(path) or "問題なし")
made.zip 問題なし
slip.zip ['「..」を含む: ../evil.txt', '「..」を含む: ../../evil2.txt', '「..」を含む: docs/../../evil3.txt']
abs.zip ['絶対パス: /abs.txt', '絶対パス: C:/drive.txt']
abs.zip は writestr で「/abs.txt」「C:/drive.txt」「ok/readme.txt」を入れたテスト用の ZIP です(展開はしていません)。file_size は ZIP に書かれた自己申告の値なので、この関数は「明らかに怪しいものを止める」最初の関門と考えてください。配布元がハッシュ値を公開していれば、ハッシュ生成ツールなどで照合してから開くとより安心です。
ZIP 爆弾にも注意する
公式ドキュメントの「展開の落とし穴(Decompression pitfalls)」には、ZIP 爆弾(小さいのに展開すると巨大になる ZIP)でディスクを使い果たすおそれがあると書かれています。上の関数のように、展開前にサイズの合計とファイル数に上限を設けておきます(ZIP 爆弾での実験はしていません)。
日本語のファイル名が化けるとき(metadata_encoding)
ZIP の仕様では、ファイル名は CP437(昔の IBM PC の文字コード)か UTF-8 で書き、UTF-8 のときは印(フラグ)を付けます。ところが、日本語版 Windows のツールには、印なしで Shift_JIS(CP932)の名前を書くものがあります。Windows 標準の tar.exe(bsdtar 3.8.9)で「jp/日本語メモ.txt」を ZIP にし(tar -a -c -f jp_tar.zip jp)、Python で読みました。
import zipfile
with zipfile.ZipFile("jp_tar.zip") as z:
for info in z.infolist():
print(info.filename, "UTF-8の印:", bool(info.flag_bits & 0x800))
with zipfile.ZipFile("jp_tar.zip", metadata_encoding="cp932") as z:
print(z.namelist())
z.extractall("jp_fixed")
jp/ UTF-8の印: False
jp/ô·û{îΩâüâé.txt UTF-8の印: False
['jp/', 'jp/日本語メモ.txt']
印のない名前を Python は CP437 として読むため、「ô·û{îΩâüâé.txt」と化けました。Python 3.11 で追加された metadata_encoding=”cp932″ を付けると正しい名前で読め、jp_fixed に「日本語メモ.txt」として展開されました。0x800 は「名前は UTF-8」を表す印のビットです。
Python の zipfile で作った ZIP は、公式ドキュメントのとおり ASCII 以外の名前を UTF-8 で書き、印も付きました。印のある名前には metadata_encoding は効きません(公式ドキュメントでも印が優先)。metadata_encoding は読むとき専用で、”w” で付けると ValueError: metadata_encoding is only supported for reading files になりました。文字コードの仕組みは「文字コードとは?」を参照してください。
is_zipfile と testzip で壊れた ZIP を見分ける
is_zipfile() は ZIP の形式かどうか(ファイルの印)を調べ、testzip() は中のファイルをすべて読んで CRC(壊れていないかを調べる検査値)を確かめ、最初に見つかった壊れたファイルの名前を返します(なければ None)。圧縮していない stored.zip をコピーし、1,000 バイト目を 1 ビットだけ変えて試しました。
import shutil
import zipfile
print(zipfile.is_zipfile("made.zip"))
print(zipfile.is_zipfile("project/README.md"))
shutil.copy("stored.zip", "broken.zip")
with open("broken.zip", "r+b") as f:
f.seek(1000)
b = f.read(1)
f.seek(1000)
f.write(bytes([b[0] ^ 0x01]))
with zipfile.ZipFile("made.zip") as z:
print(z.testzip())
with zipfile.ZipFile("broken.zip") as z:
print(z.testzip())
True
False
None
project/data/sales.csv
壊れた ZIP も is_zipfile では True でした(別に確認)。中身まで確かめるには testzip を使います。壊れたファイルを read() すると zipfile.BadZipFile: Bad CRC-32 for file 'project/data/sales.csv' になりました。ZIP でないファイルを ZipFile() で開くと BadZipFile: File is not a zip file になります。
パスワード付き ZIP は読めるが作れない
公式ドキュメントには「暗号化されたファイルの復号はできるが、今のところ暗号化されたファイルは作れない」「復号は C ではなく Python で書かれているため、とても遅い」と書かれています。読むときは z.extractall("out", pwd=b"password") のように、パスワードを bytes で渡します(setpassword() で先に設定することもできます)。パスワード付き ZIP を作りたいときは、zipfile 以外の方法が必要です。この記事では、パスワード付き ZIP を読む動作は確かめていません。
よくある間違い
ZIP を圧縮するフォルダーの中に作ってしまう
上の zip_dir で zip_dir("project2", "project2/backup.zip") のように、圧縮するフォルダーの中に ZIP を作ると、書き込み中の backup.zip 自身が rglob で見つかり、0 バイトの backup.zip が ZIP の中に入りました。ZIP はフォルダーの外に作りましょう。
“a” で同じ名前を足して「上書き」したつもりになる
“a” で同じ名前のファイルを足すと、UserWarning: Duplicate name: 'project/README.md' という警告が出て、同じ名前が 2 つ入りました。中身を差し替えたいときは、新しい ZIP を作り直します。
よくある質問
.tar.gz を扱うには?
zipfile では扱えないので、標準ライブラリの tarfile か shutil.make_archive(形式に “gztar”)を使います。tarfile で展開するときの filter=”data” については「tar・zipで圧縮・展開する方法」で説明しています。
まとめ
- ZipFile は with で開く。”w” は黙って上書き、上書きしたくなければ “x”
- compression=zipfile.ZIP_DEFLATED を付けないと圧縮されない
- arcname に relative_to() の結果を渡して、ZIP の中の名前を整える
- 受け取った ZIP は namelist・infolist で確かめてから、空のフォルダーに展開する
- 日本語名が化けたら metadata_encoding=”cp932″(Python 3.11 以降)
関連する記事・ツール
- tar・zipで圧縮・展開する方法|LinuxとWindowsのコマンド・文字化け対策
- Pythonのpathlibの使い方|Pathでファイル・フォルダーを操作する方法と注意点
- Pythonのファイル読み書き|open・with・encoding指定と文字化けの直し方
- Pythonのwith文とは?コンテキストマネージャーの仕組みと作り方
- 文字コードとは?UTF-8・Shift_JIS・EUC-JPの違いと文字化けの原因・直し方