pip install Pillow fails on Alpine Linux with a jpeg error
The 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.
Fix it fast
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 302Match what you see, then jump to its fix
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 Pillow3Verify
pip finishes the Pillow build and the package is listed.
pip show PillowConfirmed by pillow.readthedocs.io
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.txt2Fix
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=disable3Verify
The build completes without asking for the jpeg headers.
pip show PillowConfirmed by pillow.readthedocs.io
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:
- stegnor.comMy company site: 804 pages from a Python and Jinja generator, with 15 free browser tools.
- MenuloA restaurant discovery platform in Germany, kept current by a Python ingestion pipeline.
- ShopGoAn e-commerce aggregator with a Python scraping engine behind its catalog, past 10K Google Play downloads.
Related fixes
Servers
pip install confluent-kafka fails because librdkafka/rdkafka.h is missing
pip stops while building confluent-kafka from source
The error means pip is compiling confluent-kafka from source, and the compiler cannot find the librdkafka C headers.
3 causes, each with a fixServers
cv2.imshow raises 'not implemented' because the wrong OpenCV package is installed
cv2.imshow() works in one environment and fails in another
The headless OpenCV packages are built without any GUI code, so cv2.imshow cannot open a window.
2 causes, each with a fixServers
pip install Cython succeeded, but the shell cannot find cythonize
a pip warning that a script was installed to a directory outside PATH
pip put the cythonize script in a folder your shell does not search.
3 causes, each with a fixServers
Django returns a 500 behind Gunicorn and the traceback is nowhere
The traceback shows locally with runserver but not under Gunicorn
With DEBUG set to False, Django's default logging does not print errors to the console.
2 causes, each with a fixServers
Docker build fails with apk: not found in a Python or Ubuntu image
/bin/sh: 1: apk: not found
apk is the package manager of Alpine Linux only.
2 causes, each with a fixServers
You cannot pip install packages inside an Ubuntu Docker container
error: externally-managed-environment
If pip is missing, install the python3-pip package with apt, in the same RUN as apt-get update.
3 causes, each with a fix