Python compression.zstd 사용법

본문 중간의 쿠팡 추천 상품 구매시 쿠팡 파트너스에서 일정액의 수수료를 제공받습니다.

Python 3.14부터 표준 라이브러리에서 compression.zstd 모듈을 사용할 수 있습니다. Zstandard 형식의 데이터를 파일처럼 읽고 쓰거나, 메모리의 bytes를 한 번에 압축하고 풀거나, 큰 데이터를 스트리밍 방식으로 처리할 때 쓰는 모듈입니다.

핵심 기준은 간단합니다. .zst 파일을 다루면 compression.zstd.open()을 먼저 보고, 작은 bytes 데이터면 compress()와 decompress()를 쓰며, 입력이 크거나 조각 단위로 들어오면 ZstdCompressor와 ZstdDecompressor를 검토하면 됩니다.

compression.zstd는 무엇인가

compression.zstd는 Zstandard 형식과 호환되는 압축·해제 기능을 제공하는 Python 표준 라이브러리 모듈입니다. Python 3.14에 추가됐고, 공식 문서 기준으로 선택 모듈입니다. 배포판이 해당 선택 모듈을 포함하지 않으면 import가 실패할 수 있으므로, 실제 배포 환경에서는 사용 가능 여부를 확인해야 합니다.

모듈은 세 가지 사용 경로를 제공합니다. 파일 인터페이스, 메모리 일괄 처리 함수, 증분 압축·해제 객체입니다.

상황	먼저 볼 API	판단 기준
.zst 파일을 읽거나 쓴다	compression.zstd.open()	파일 객체처럼 처리하고 싶을 때 적합합니다.
작은 bytes를 한 번에 처리한다	compress(), decompress()	입력과 출력이 메모리에 올라와도 무리가 없을 때 단순합니다.
큰 데이터나 스트림을 조각으로 처리한다	ZstdCompressor, ZstdDecompressor	버퍼링과 flush 시점을 직접 제어해야 할 때 필요합니다.

파일은 어떻게 읽고 쓰나

compression.zstd.open()은 Zstandard 압축 파일을 바이너리 모드나 텍스트 모드로 열 수 있습니다. 기본 읽기 모드는 rb이고, 쓰기는 wb, 추가 쓰기는 ab, 새 파일 생성은 xb를 사용할 수 있습니다. 텍스트 모드는 rt, wt처럼 지정합니다.

from compression import zstd

rows = ["alpha\n", "beta\n", "gamma\n"]

with zstd.open("sample.txt.zst", "wt", encoding="utf-8") as f:
    f.writelines(rows)

with zstd.open("sample.txt.zst", "rt", encoding="utf-8") as f:
    text = f.read()

읽을 때는 level 인자를 주면 TypeError가 납니다. 압축 레벨은 쓰기 쪽 설정이기 때문입니다. 쓰기에서는 level이나 고급 options를 줄 수 있지만, 둘을 동시에 쓰는 방식은 피해야 합니다.

메모리 데이터는 어떻게 처리하나

입력 전체가 이미 bytes이고 크기가 충분히 작다면 모듈 함수가 가장 단순합니다. compress()는 압축된 bytes를 반환하고, decompress()는 원래 bytes를 반환합니다.

from compression import zstd

payload = b"event=login\n" * 100
compressed = zstd.compress(payload, level=3)
restored = zstd.decompress(compressed)

assert restored == payload

level은 압축 수준을 제어합니다. 더 세밀한 압축 파라미터가 필요하면 CompressionParameter와 options를 사용합니다. 다만 일반적인 애플리케이션 코드에서는 먼저 기본값이나 단순한 level부터 검토하는 편이 유지보수에 유리합니다.

 

 

스트리밍 처리는 언제 필요한가

로그 파일, 네트워크 응답, 큰 백업 데이터처럼 전체 입력을 한 번에 메모리에 올리기 어렵다면 증분 객체를 사용합니다. ZstdCompressor는 compress() 호출 결과를 이어 붙이고, 마지막에는 flush()로 남은 데이터를 마무리합니다.

from compression import zstd

compressor = zstd.ZstdCompressor(level=3)
parts = []

for chunk in chunks:
    parts.append(compressor.compress(chunk))

parts.append(compressor.flush())
compressed = b"".join(parts)

ZstdCompressor의 compress()는 내부 버퍼링 때문에 항상 압축 데이터를 바로 반환하지 않을 수 있습니다. 반환값이 빈 bytes일 수 있으므로, 호출 결과를 누적하고 마지막 flush()까지 포함해야 완성된 프레임을 얻습니다.

압축 중간에 데이터를 소비자에게 빨리 넘겨야 한다면 FLUSH_BLOCK과 FLUSH_FRAME의 의미를 구분해야 합니다. FLUSH_BLOCK은 현재 블록을 내보내지만 과거 데이터를 이후 블록에서 참조할 수 있고, FLUSH_FRAME은 프레임을 끝내므로 이후 데이터는 새 프레임으로 이어집니다.

다중 프레임 입력은 무엇을 조심해야 하나

공식 문서 기준으로 decompress() 함수는 여러 개의 압축 프레임이 이어 붙은 입력을 모두 풀어서 결과를 이어 반환합니다. ZstdFile도 파일 객체를 다룰 때 이 흐름에 맞습니다.

반면 ZstdDecompressor 클래스는 여러 압축 프레임을 투명하게 한 번에 처리하지 않습니다. 증분 해제 객체를 직접 쓰는 코드라면 eof, unused_data, needs_input 상태를 확인하고, 프레임이 여러 개인 입력에서는 새 decompressor를 만드는 흐름을 고려해야 합니다.

딕셔너리는 언제 검토하나

Zstandard dictionary는 비슷한 작은 데이터 조각을 많이 압축할 때 효율을 높이기 위한 기능입니다. train_dict(samples, dict_size)로 샘플 기반 딕셔너리를 만들고, 압축과 해제 양쪽에서 같은 딕셔너리를 전달합니다.

딕셔너리는 모든 압축 작업의 기본 선택지는 아닙니다. 데이터가 충분히 크거나 서로 비슷하지 않으면 관리 비용이 이점보다 클 수 있습니다. 작은 JSON 메시지, 비슷한 로그 레코드, 같은 스키마의 이벤트처럼 반복 구조가 많은 데이터에서 먼저 검토하는 편이 맞습니다.

gzip, zlib, zipfile과 어떻게 구분하나

compression.zstd는 Zstandard 형식을 다루기 위한 모듈입니다. 이미 상대 시스템이 .gz를 요구하면 gzip을 쓰고, zlib 스트림이나 gzip 헤더 옵션을 직접 제어해야 하면 zlib을 봅니다. ZIP 아카이브 파일 안의 항목을 다루는 문제라면 zipfile이 별도 선택지입니다.

목적	기본 선택	주의할 점
.zst 파일 또는 raw zstd 스트림	compression.zstd	Python 3.14 이상과 선택 모듈 포함 여부를 확인합니다.
.gz 파일	gzip	호환 대상이 gzip 형식을 요구할 때 맞습니다.
zlib·deflate 세부 제어	zlib	wbits, strategy 같은 세부 옵션을 다룹니다.
여러 파일을 묶은 ZIP 아카이브	zipfile	압축 알고리즘보다 아카이브 구조가 핵심입니다.

실무 기준

첫째, 파일 확장자나 상대 시스템의 요구 형식이 .zst라면 compression.zstd를 쓰는 것이 자연스럽습니다. 표준 라이브러리에 들어온 뒤에는 별도 패키지 의존을 줄일 수 있습니다.

둘째, 입력 크기에 따라 API를 고릅니다. 작고 독립적인 데이터는 compress()와 decompress()가 단순하고, 큰 데이터는 증분 객체나 파일 인터페이스를 쓰는 편이 안전합니다.

셋째, 고급 옵션은 필요가 확인된 뒤에만 올립니다. 압축 레벨, dictionary, window 같은 파라미터는 데이터 특성과 운영 환경에 따라 결과가 달라집니다. 객관적인 비교가 필요하면 실제 데이터 샘플로 압축률, 처리 시간, 메모리 사용량을 따로 측정해야 합니다.

넷째, 호환성을 확인합니다. Python 3.13 이하에서는 compression.zstd가 없고, Python 3.14에서도 선택 모듈이 빠진 빌드일 수 있습니다. 라이브러리 코드라면 import 실패 시 대체 경로나 명확한 오류 메시지를 준비하는 것이 좋습니다.

FAQ

compression.zstd는 Python 3.13에서도 쓸 수 있나

아닙니다. compression.zstd는 Python 3.14에 추가된 모듈입니다. Python 3.13 이하를 지원해야 하는 프로젝트라면 별도 의존성이나 조건부 구현을 검토해야 합니다.

zstd를 쓰면 항상 gzip보다 낫다고 봐도 되나

그렇게 단정하면 안 됩니다. Zstandard는 빠른 무손실 압축 알고리즘으로 널리 쓰이지만, 실제 선택은 호환 대상, 파일 형식 요구, 데이터 특성, 배포 환경에 따라 달라집니다. 이미 gzip 형식을 요구하는 시스템에는 gzip을 맞춰야 합니다.

dictionary는 기본으로 켜야 하나

아닙니다. dictionary는 비슷한 작은 데이터가 반복될 때 검토할 기능입니다. 압축과 해제 양쪽에서 같은 dictionary를 관리해야 하므로, 이점이 확인되지 않은 일반 파일 압축에는 먼저 단순 API를 쓰는 편이 낫습니다.

ZstdDecompressor 하나로 이어 붙은 프레임을 모두 처리해도 되나

주의해야 합니다. 공식 문서는 ZstdDecompressor 클래스가 여러 프레임 입력을 투명하게 처리하지 않는다고 설명합니다. 여러 프레임 가능성이 있으면 decompress(), ZstdFile, 또는 프레임별 decompressor 흐름을 선택합니다.