Python
PR

Pythonのzipfileの使い方|ZIPの作成・展開と圧縮・文字化け・安全な展開

Pythonのzipfileの使い方|ZIPの作成・展開と圧縮・文字化け・安全な展開
hr
記事内に商品プロモーションを含む場合があります

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() などに渡す名前も / で書きます。

work の中の project フォルダーのファイルを ZIP に入れるとき、arcname なしで絶対パスを渡すと Users から始まる名前、relative_to(work) なら project/README.md、relative_to(project) なら README.md になる
図 1:arcname の付け方と ZIP の中の名前

フォルダーごと圧縮する関数(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_archivezipfile で自作
書く量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(パストラバーサルの一種)と呼ばれます。

ZIP の中の名前 ../evil.txt を out に展開するとき、名前をそのままつなぐと out の外の work/evil.txt に書き込まれる。Python の extract は .. を取り除き、out の中の work/out/evil.txt に作る
図 2:../ 入りの名前の展開先

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 以降)

関連する記事・ツール

ABOUT ME
hr
hr
エンジニアとして働いている hr です。仕事や資格勉強で「こんなツールがあれば」と感じたものを、無料Webツールと解説記事にして発信しています。
記事URLをコピーしました