AWS Lambda LayersでPillowの「_imaging」エラーを解決！現場エンジニアが教える構築法

Pillow (PIL) と Lambda Layers の連携における課題
- Pillow を Lambda Layers に正しく含めるメリット
- 現場での注意点とハマりどころ
結論：環境差異を意識したレイヤー構築が鍵

Pillow (PIL) と Lambda Layers の連携における課題

AWS Lambda Layers で Pillow (PIL) を利用する際、しばしば 「cannot import _imaging from PIL」 というエラーに直面する。これは、Lambda の実行環境とローカルでのライブラリビルド環境の差異、あるいはレイヤーの構造設定ミスが原因だ。

筆者の経験上、このエラーは特にネイティブ依存ライブラリが原因で発生することが多い。これを解決し、Pillow を Lambda Layers に正しく含めることは、いくつかの重要なメリットをもたらす。

Pillow を Lambda Layers に正しく含めるメリット

デプロイパッケージサイズの削減: 依存ライブラリをレイヤーとして分離することで、Lambda 関数のデプロイパッケージが軽量化される。これにより、デプロイ時間の短縮とコールドスタートの改善が期待できる。
依存関係の管理容易性: 複数の Lambda 関数で共通のライブラリを使用する場合、レイヤーで一元管理すれば、各関数での重複管理の手間が省ける。
開発サイクルの高速化: アプリケーションコードの変更に集中でき、ライブラリの更新・管理が効率化される。

現場での注意点とハマりどころ

Pillow のビルドでは、OS レベルのネイティブライブラリ（例: libjpeg, zlib）が必要となる場合が多い。ローカル環境で pip install したものと Lambda の実行環境では、これらのライブラリの有無やバージョンが異なるため、そのままでは動作しないことが頻発する。これが _imaging エラーの主な原因だ。

具体的な注意点:

アーキテクチャの整合性: Lambda 関数とレイヤーのアーキテクチャ（x86_64 または arm64）は必ず一致させよ。
Python バージョンの互換性: Lambda ランタイムの Python バージョンと、レイヤーで使用する Python バージョンは合わせるべきだ。
ネイティブ依存関係: Pillow が依存するネイティブライブラリが Lambda 環境に存在しない、またはバージョンが合わない場合、_imaging のインポートエラーが発生する。
レイヤーの構造: Lambda Layers は python/lib/pythonX.Y/site-packages といった特定のディレクトリ構造を期待する。Pillow がこの構造に沿って配置されていないと、インポート時に認識されない。

筆者の経験上、これらの環境差異による問題を回避する最も確実な方法は、AWS SAM (Serverless Application Model) や Serverless Framework を使用し、ビルドプロセスを自動化・管理することだ。

これらのツールは Docker などで Lambda の実行環境をエミュレートし、その環境下でライブラリをビルド・パッケージ化できるため、環境差異による問題を効果的に回避できる。

# AWS SAM CLI を使用した Lambda Layer のビルド例 (template.yaml): 

AWSTemplateFormatVersion: '2010-09-09'
Transform: AWS::Serverless-2016-10-31
Description: Example Lambda Layer for Pillow

Resources:
  PillowLayer:
    Type: AWS::Serverless::LayerVersion
    Properties:
      LayerName: pillow-layer
      Description: Pillow library for Lambda
      ContentUri: src/ # Pillow をインストールするディレクトリ
      CompatibleRuntimes:
        - python3.9
      # BuildMethod: ruby # 例: Ruby の場合。Python の場合は自動検出される

# src/ ディレクトリ内に requirements.txt を配置し、Pillow を記述する。
# 例: requirements.txt
# pillow

# sam build コマンドでビルドすると、src/ ディレクトリの内容が Lambda Layer 用にパッケージ化される。
# sam build --use-container

結論：環境差異を意識したレイヤー構築が鍵

AWS Lambda Layers で Pillow (PIL) を利用する際の _imaging エラーは、ローカル環境と Lambda 実行環境の差異、特にネイティブ依存関係の欠如やアーキテクチャ・バージョンの不一致が根本原因だ。

これを解決するには、Lambda の実行環境をエミュレートできるツール（AWS SAM CLI, Serverless Framework）を活用し、レイヤーのビルドプロセスを標準化・自動化することが最も効果的である。

これにより、デプロイの安定性と開発効率を大幅に向上させることができる。このアプローチは、現場の多くのエンジニアが採用しているベストプラクティスだ。