Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

pip install Pillow fails on Alpine Linux with a jpeg error

ErrorThe headers or library files could not be found for jpeg, a required dependency when compiling Pillow from source.

Short answer

Pillow needs the libjpeg headers when pip has to compile it, and an Alpine image does not have them. Add jpeg-dev and zlib-dev (the official list adds more) with apk before pip install. If you never read or write JPEG files, you can tell the build to disable that feature instead.

  • Applies to Alpine Linux 3.20, Python 3.12, Pillow 11
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Confirm the build is compiling Pillow from source and see which library it names.

    pip install --no-cache-dir Pillow 2>&1 | tail -n 30
  2. 2Match what you see, then jump to its fix

    1. 1The error names jpeg (or zlib) as a required dependencyThe jpeg and zlib development packages are missingFix
    2. 2The image only handles PNG or other formats and you want a small buildYou do not need JPEG support at allFix

What does the error look like?

  • The headers or library files could not be found for jpeg, a required dependency when compiling Pillow from source.
  • RequiredDependencyException: jpeg

Cause 1 of 2

The jpeg and zlib development packages are missing

1Check

libjpeg and zlib are required by default when Pillow is built from source. The Pillow build guide lists the Alpine packages that provide the headers.

apk info | grep -E 'jpeg-dev|zlib-dev'

2Fix

Install the development packages before pip runs. This is the list from the Pillow build guide for Alpine; trim it if you do not need every format.

apk add tiff-dev jpeg-dev openjpeg-dev zlib-dev freetype-dev lcms2-dev \
    libwebp-dev tcl-dev tk-dev harfbuzz-dev fribidi-dev libimagequant-dev \
    libxcb-dev libpng-dev
pip install Pillow

3Verify

pip finishes the Pillow build and the package is listed.

pip show Pillow

Confirmed by pillow.readthedocs.io

Did this fix it?

Cause 2 of 2

You do not need JPEG support at all

1Check

JPEG and zlib are required by default, but the guide says each can be disabled with a build setting.

grep -i pillow requirements.txt

2Fix

Pass the documented setting to pip. Note that the resulting Pillow cannot open JPEG files. Zlib has the same switch (-C zlib=disable).

pip install Pillow -C jpeg=disable

3Verify

The build completes without asking for the jpeg headers.

pip show Pillow

Confirmed by pillow.readthedocs.io

Did this fix it?

How do I stop it coming back?

  • Put the apk add line in the Dockerfile before the pip install step, so the layer is cached.
  • Decide which image formats the app really needs and install only those libraries.
  • Read the Pillow build guide when you bump the Pillow major version, because the library list changes.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.