Docker 환경에서 Python 애플리케이션을 배포할 때, 이미지 빌드 시간이 지나치게 오래 걸리거나 gcc 등 컴파일러 의존성 문제로 빌드가 실패하는 경험을 종종 하게 됩니다. 이때 가장 효과적인 해결책 중 하나가 바로 Python Wheel을 활용하는 것입니다.

이 글에서는 Python Wheel의 개념과 장점, 그리고 Dockerfile에서 이를 활용하여 빌드 과정을 최적화하는 방법을 알아봅니다.

1. Python Wheel이란 무엇인가?

Commandbox 광고

Wheel(.whl) 은 Python의 바이너리 배포 포맷(Built Distribution) 입니다.

일반적으로 Python 패키지는 두 가지 형태로 배포됩니다.

  1. Source Distribution (sdist, .tar.gz): 소스 코드 형태입니다. 설치 시 사용자의 컴퓨터에서 컴파일(Build) 과정이 필요합니다.

  2. Built Distribution (bdist_wheel, .whl): 미리 컴파일된 바이너리 형태입니다. 설치 시 별도의 컴파일 없이 파일만 복사하여 설치가 완료됩니다.

쉽게 비유하자면, 소스 배포판은 '조립이 필요한 가구'이고, Wheel은 '완성된 가구'입니다. Wheel을 사용하면 조립하는 시간과 도구(컴파일러)가 필요 없습니다.

2. 일반적인 pip install과의 차이점

우리가 흔히 사용하는 pip install <package> 명령어를 실행할 때, 내부적으로는 다음과 같은 우선순위로 작동합니다.

  1. Wheel 파일이 존재할 경우: 해당 바이너리를 다운로드하여 즉시 설치합니다. (매우 빠름)

  2. Wheel 파일이 없을 경우: 소스 파일(tar.gz)을 다운로드한 후, 로컬 환경에서 컴파일(Build)을 수행하고 설치합니다. (느림, 컴파일 도구 필요)

차이점 요약 표

구분 Source Distribution (sdist) Wheel (whl)
확장자 .tar.gz, .zip .whl
설치 과정 다운로드 -> 컴파일 -> 설치 다운로드 -> 설치
설치 속도 느림 (컴파일 시간 소요) 매우 빠름
필요 도구 컴파일러 (gcc, g++, 헤더 파일 등) 없음 (pip만 있으면 됨)
OS 의존성 컴파일 시점의 환경에 따름 빌드된 OS/아키텍처에 종속됨

3. Dockerfile에서 Wheel을 사용하는 이유 (장점)

Commandbox 광고

Docker 환경, 특히 Multi-stage Build(멀티 스테이지 빌드)에서 Wheel을 사용하면 다음과 같은 명확한 이점이 있습니다.

  1. 빌드 속도 비약적 향상: pandas, numpy와 같이 C/C++로 작성된 무거운 라이브러리를 매번 컴파일하지 않아도 됩니다.

  2. 이미지 크기 경량화: 최종 실행 이미지(Runtime Image)에는 gcc, build-essential과 같은 무거운 컴파일 도구를 포함할 필요가 없습니다.

  3. 안정성 확보: 네트워크 문제나 외부 저장소의 일시적 장애로 인해 빌드가 깨지는 것을 방지하고, 로컬에서 미리 빌드된 파일을 사용할 수도 있습니다.

4. Dockerfile 작성 및 사용법

Wheel을 활용한 Docker 빌드는 주로 Builder 스테이지에서 Wheel 파일을 생성하고, Final 스테이지에서 이를 가져와 설치하는 방식으로 이루어집니다.

예제: Multi-stage Build를 활용한 Dockerfile

아래는 C 라이브러리 의존성이 있는 패키지를 효율적으로 설치하는 패턴입니다.

# [Stage 1] Builder: Wheel 파일 생성
FROM python:3.9-slim as builder

# 컴파일을 위한 필수 패키지 설치 (최종 이미지에는 포함되지 않음)
RUN apt-get update && apt-get install -y \
    build-essential \
    gcc \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

# requirements.txt 복사
COPY requirements.txt .

# pip wheel 명령어로 .whl 파일들을 /wheels 디렉토리에 생성
# -w: wheel 파일을 저장할 경로 지정
RUN pip wheel --no-cache-dir --no-deps --wheel-dir /app/wheels -r requirements.txt


# [Stage 2] Final: 실행 이미지
FROM python:3.9-slim

WORKDIR /app

# Builder 스테이지에서 생성된 Wheel 파일들만 복사
COPY --from=builder /app/wheels /wheels
COPY --from=builder /app/requirements.txt .

# Wheel 파일을 이용하여 패키지 설치
# --no-index: PyPI 인덱스를 무시하고 로컬 파일만 찾음
# --find-links: 설치할 패키지를 찾을 경로 지정
RUN pip install --no-cache --no-index --find-links=/wheels -r requirements.txt \
    && rm -rf /wheels

# 애플리케이션 코드 복사
COPY . .

CMD ["python", "main.py"]

핵심 명령어 설명

  • pip wheel: 패키지를 설치하지 않고, 해당 환경에 맞는 .whl 파일을 생성하여 지정된 디렉토리에 저장합니다.

  • --wheel-dir: 생성된 Wheel 파일이 저장될 위치입니다.

  • --find-links=/wheels: PyPI 서버(인터넷)에서 패키지를 다운로드하는 대신, 지정된 로컬 경로에서 패키지를 찾도록 지시합니다.

마치며

Docker 빌드 시 Python Wheel을 활용하는 것은 선택이 아닌 필수 최적화 기법에 가깝습니다. 특히 CI/CD 파이프라인에서 반복적인 빌드가 일어나는 환경이라면, 빌드 시간을 단축하고 이미지 사이즈를 줄이는 것만으로도 큰 비용 절감 효과를 얻을 수 있습니다.

지금 작성 중인 Dockerfile에 gcc 설치 과정이 포함되어 있다면, Wheel을 이용한 멀티 스테이지 빌드로 전환해 보시기 바랍니다.

python-wheel-concept-image