Lambda 외부 라이브러리 적용 가이드 (ZIP, Layer, Docker)

AWS Lambda에서 boto3 같은 기본 라이브러리 외에 다른 패키지를 사용하려면 직접 포함시켜야 합니다. 이 글에서는 Lambda에 외부 라이브러리를 추가하는 3가지 방법(ZIP, Layer, Docker)과 주의사항을 정리합니다.

 

1. ZIP 업로드

가장 기본적인 방법입니다. 코드와 라이브러리를 함께 압축해서 업로드하는 방식입니다.

디렉토리 구조

lambda.zip/
├── handler.py          # Lambda 코드
├── pypdfium2/          # 외부 라이브러리
├── PIL/                # 외부 라이브러리
└── ...

 

패키지 설치 방법

Lambda는 Amazon Linux 환경에서 실행되기 때문에, Windows나 Mac에서 작업할 경우 반드시 Linux용 바이너리를 받아야 합니다.

방법 1: pip 옵션 사용

pip install \
  --platform manylinux2014_x86_64 \
  --only-binary=:all: \
  -r requirements.txt \
  -t package/

옵션	의미
--platform manylinux2014_x86_64	Linux용 바이너리 다운로드 강제
--only-binary=:all:	소스 컴파일 없이 바이너리만 설치
-r requirements.txt	설치할 패키지 목록 파일
-t package/	라이브러리가 설치될 타겟 폴더 지정

 

방법 2: Docker 사용

로컬 환경과 무관하게 리눅스 컨테이너 안에서 패키지를 설치하는 확실한 방법입니다.

docker run --rm -v $(pwd):/var/task \
  python:3.14-slim \
  pip install -r /var/task/requirements.txt -t /var/task/package/

옵션	의미
--rm	컨테이너 종료 후 자동 삭제
-v $(pwd):/var/task	현재 폴더를 컨테이너 내부로 마운트
python:3.14-slim	Python 3.14 Linux 이미지 사용
-t /var/task/package/	설치 경로 지정

 

ZIP 파일 생성

# handler.py를 package 폴더에 복사
cp handler.py package/

# ZIP 만들기
cd package
zip -r ../lambda.zip .

 

장단점 요약

장점	단점
구성이 간단함	함수마다 라이브러리가 중복됨
배포 과정이 직관적임	코드 수정 시 전체(라이브러리 포함) 다시 업로드 필요

 

2. Layer (계층)

라이브러리를 별도의 Layer로 분리해서 여러 Lambda 함수에서 공유하는 방식입니다.

ZIP 방식 vs Layer 방식 구조 비교

[ZIP 방식: 중복 발생]

Lambda 함수 A (zip)
├── handler.py
├── pypdfium2/
└── pillow/

Lambda 함수 B (zip)
├── handler.py
├── pypdfium2/    (중복)
└── pillow/       (중복)

 

[Layer 방식: 공유]

Layer (공용 라이브러리)
├── pypdfium2/
└── pillow/

Lambda 함수 A
└── handler.py   (Layer 참조)

Lambda 함수 B
└── handler.py   (Layer 참조)

 

 

Layer용 ZIP 생성

Layer는 반드시 특정 폴더 구조(python/)를 지켜야 인식됩니다.

mkdir -p layer/python
pip install \
  --platform manylinux2014_x86_64 \
  --only-binary=:all: \
  -r requirements.txt \
  -t layer/python/

cd layer
zip -r ../layer.zip python/

 

장단점 요약

장점	단점
여러 함수에서 라이브러리 재사용 가능	Layer 버전 및 권한 관리 필요
소스 코드 수정 시 handler.py만 가볍게 업로드	초기 설정이 ZIP 방식보다 복잡함

 

3. Docker 이미지

컨테이너 이미지로 말아서 Lambda를 배포하는 방식입니다.

 

Dockerfile 예시

FROM public.ecr.aws/lambda/python:3.14

COPY requirements.txt .
RUN pip install -r requirements.txt

COPY handler.py .

CMD ["handler.handler"]

 

장단점 요약

장점	단점
최대 10GB까지 패키지 포함 가능	콜드 스타트(초기 구동) 속도가 느릴 수 있음
OS 의존성 등 복잡한 환경 구성 가능	AWS ECR(Container Registry) 사용 필요
로컬 테스트가 용이함	설정 및 배포 파이프라인이 복잡함

 

선택 가이드: 언제 무엇을 쓸까?

상황	추천 방식
Lambda가 1~2개이고, 빠르게 개발하고 싶을 때	ZIP 업로드
여러 Lambda가 동일한 라이브러리를 사용할 때	Layer
라이브러리 용량이 크거나(250MB 초과), OS 의존성이 복잡할 때	Docker 이미지

 

주의사항: 플랫폼(OS) 호환성 문제

 

C언어 기반의 바이너리가 포함된 패키지(pillow, numpy, pypdfium2 등)는 OS별로 빌드된 파일이 다릅니다. 개발자의 PC 환경과 Lambda의 실행 환경이 다르면 오류가 발생합니다.

개발 환경 (내 PC)	설치되는 파일	Lambda (Linux) 실행 결과
Windows	Windows용 바이너리	오류 발생
Mac (M1/M2 등)	Mac(ARM)용 바이너리	오류 발생
Linux	Linux용 바이너리	정상 동작

 

소스 코드 vs 바이너리

• 소스 코드: 사람이 읽을 수 있는 텍스트 형태. 컴파일 과정이 필요하므로 Lambda 실행 시점에 바로 사용할 수 없습니다.
• 바이너리: 컴퓨터(OS)가 바로 실행할 수 있는 기계어 파일.

Lambda 런타임에는 컴파일러(gcc 등)가 포함되어 있지 않습니다. 따라서 로컬에서 미리 Linux 환경에 맞는 바이너리를 다운로드하거나 빌드해서 올려야 합니다. 앞서 설명한 --platform manylinux2014_x86_64 옵션이나 Docker를 사용하는 이유가 바로 이것입니다.

 

정리

• ZIP 업로드: 소규모 프로젝트에 적합한 기본 방법
• Layer: 중규모 이상, 함수 간 코드 공유가 필요할 때
• Docker: 대용량 라이브러리나 복잡한 환경이 필요할 때

처음에는 ZIP 방식으로 시작하여 구조를 잡고, 프로젝트가 커짐에 따라 Layer나 Docker로 전환하는 것을 추천합니다.