{{tag>[cli python zip archive standard-library]}}

====== python -m zipfile ======
Python의 ZIP 아카이브 기본 모듈인 ''zipfile''을 명령줄에서 실행하여 파일 목록 확인, 생성, 압축 해제, 무결성 검사를 수행한다.

===== Summary =====
  * ''zipfile''은 Python Standard Library에 포함된 **기본 모듈**이다.
  * 별도 ''pip install'' 없이 설치된 Python 인터프리터로 실행한다.
  * 단순한 ZIP 작업은 ''python -m zipfile''로 처리하고, 세부 압축 방식이나 암호화 같은 고급 제어가 필요하면 Python API 또는 전용 도구를 사용한다.

===== Installation =====
''zipfile''은 Python 기본 모듈이므로 별도 설치가 필요하지 않다. Python이 설치되어 있으면 다음 명령으로 모듈과 CLI 사용 가능 여부를 확인한다.

<code bash>
python --version
python -c "import zipfile; print(zipfile.__file__)"
python -m zipfile --help
</code>

환경에 따라 Python 실행 파일 이름이 ''python3''인 경우 아래처럼 바꿔 실행한다.

<code bash>
python3 -m zipfile --help
</code>

===== Usage =====
<code bash>
python -m zipfile -l archive.zip
python -m zipfile -t archive.zip
python -m zipfile -c archive.zip file.txt directory/
python -m zipfile -e archive.zip output-directory/
</code>

  * ''<color #c3c3c3>**python**</color> <color #22b14c>**-m**</color> <color #ff7f27>**zipfile**</color> <color #22b14c>**-l**</color> <color #7092be>ZIPFILE</color>'': 아카이브 멤버 목록 표시
  * ''<color #c3c3c3>**python**</color> <color #22b14c>**-m**</color> <color #ff7f27>**zipfile**</color> <color #22b14c>**-t**</color> <color #7092be>ZIPFILE</color>'': ZIP 파일 무결성 검사
  * ''<color #c3c3c3>**python**</color> <color #22b14c>**-m**</color> <color #ff7f27>**zipfile**</color> <color #22b14c>**-c**</color> <color #7092be>ZIPFILE SOURCE...</color>'': 파일 또는 디렉터리로 ZIP 생성
  * ''<color #c3c3c3>**python**</color> <color #22b14c>**-m**</color> <color #ff7f27>**zipfile**</color> <color #22b14c>**-e**</color> <color #7092be>ZIPFILE OUTPUT_DIR</color>'': 지정 디렉터리에 압축 해제

===== Options =====
  * ''<color #22b14c>**-h, --help**</color>'': 도움말 표시
  * ''<color #22b14c>**-l, --list**</color> <color #7092be>ZIPFILE</color>'': 아카이브 멤버 목록 표시
  * ''<color #22b14c>**-e, --extract**</color> <color #7092be>ZIPFILE OUTPUT_DIR</color>'': 대상 디렉터리에 압축 해제
  * ''<color #22b14c>**-c, --create**</color> <color #7092be>ZIPFILE [SOURCE...]</color>'': 소스 파일과 디렉터리로 ZIP 생성
  * ''<color #22b14c>**-t, --test**</color> <color #7092be>ZIPFILE</color>'': ZIP 파일 유효성 검사
  * ''<color #22b14c>**--metadata-encoding**</color> <color #7092be>ENCODING</color>'': ''-l'', ''-e'', ''-t''에서 멤버 이름 해석에 사용할 인코딩 지정; Python 3.11 이상

===== Examples =====
==== 목록과 무결성 확인 ====
압축을 풀기 전에 파일 목록과 무결성을 먼저 확인한다.

<code bash>
python -m zipfile --list release.zip
python -m zipfile --test release.zip
</code>

==== ZIP 아카이브 생성 ====
파일 여러 개를 하나의 아카이브로 만든다.

<code bash>
python -m zipfile --create release.zip README.txt dist/
</code>

디렉터리를 전달하면 해당 디렉터리와 하위 항목이 포함된다.

==== 지정 디렉터리에 압축 해제 ====
<code bash>
mkdir -p extracted
python -m zipfile --extract release.zip extracted/
</code>

<note warning>
신뢰할 수 없는 ZIP 파일은 먼저 목록과 크기를 확인한다. 압축 해제는 기존 파일을 별도 확인 없이 덮어쓸 수 있으며, ZIP bomb는 디스크 공간이나 메모리를 고갈시킬 수 있다. 중요한 파일이 없는 새 디렉터리를 대상으로 사용하는 것이 안전하다.
</note>

==== 레거시 파일 이름 인코딩 지정 ====
UTF-8 플래그가 없는 오래된 ZIP의 멤버 이름이 깨질 때 원래 코드 페이지를 지정한다.

<code bash>
python -m zipfile --metadata-encoding cp949 --list legacy.zip
python -m zipfile --metadata-encoding cp949 --extract legacy.zip extracted/
</code>

ZIP에 기록된 UTF-8 플래그가 있으면 그 값이 ''--metadata-encoding''보다 우선한다.

===== Help =====
++++ python3 -m zipfile --help (Python 3.12.13) |
<code text>
usage: __main__.py [-h]
                   (-l <zipfile> | -e <zipfile> <output_dir> | -c <name> [<file> ...] | -t <zipfile>)
                   [--metadata-encoding <encoding>]

A simple command-line interface for zipfile module.

options:
  -h, --help            show this help message and exit
  -l <zipfile>, --list <zipfile>
                        Show listing of a zipfile
  -e <zipfile> <output_dir>, --extract <zipfile> <output_dir>
                        Extract zipfile into target dir
  -c <name> [<file> ...], --create <name> [<file> ...]
                        Create zipfile from sources
  -t <zipfile>, --test <zipfile>
                        Test if a zipfile is valid
  --metadata-encoding <encoding>
                        Specify encoding of member names for -l, -e and -t
</code>
++++

===== Compatibility =====
  * ''--metadata-encoding''은 Python 3.11에서 추가되었다.
  * Python 실행 파일 이름은 운영체제와 설치 방식에 따라 ''python'' 또는 ''python3''일 수 있다.
  * ''zipfile''은 멀티파트 ZIP 생성을 지원하지 않으며, 암호화된 ZIP을 읽을 수는 있지만 암호화된 ZIP을 생성하지는 않는다.

===== See Also =====
  * [[python|Python]]
  * [[python:venv|venv]]
  * [[https://docs.python.org/3/library/zipfile.html|Python 공식 문서: zipfile]]
  * [[https://docs.python.org/3/library/zipfile.html#command-line-interface|Python 공식 문서: Command-line interface]]

===== History =====
  * codex:: 2026-08-03 Python 기본 모듈임을 명시하고 ''python -m zipfile'' 실행 명령, 옵션, 예제, 안전 주의를 추가.

{{indexmenu>.#1|js}}