Skip to main content

Fixing PIL/Pillow IOError: decoder zip not available

· 4 min read
Serhii Hrekov
Serhii Hrekov
software engineer, creator, artist, programmer, projects founder

The error IOError: decoder zip not available (or zip decoder not available) is a common hurdle when working with image processing in Python, particularly when handling PNG or TIFF files using the Pillow library.

This error indicates that the underlying C library responsible for image compression (Zlib) was missing or not detected when Pillow was compiled on your system.

1. The "Why": Understanding the Root Cause​

Pillow is a Python wrapper around several core image manipulation libraries written in C. It does not implement compression algorithms (like JPEG or PNG compression) from scratch in Python; instead, it links to system-level libraries.

  • JPEG support requires libjpeg.
  • PNG/Zip support requires zlib.

When you run pip install pillow, the installation script checks your system for these libraries.

  1. If zlib development headers are found: Pillow compiles with PNG/Zip support enabled.
  2. If zlib is missing: Pillow installs successfully without compression support.

The error only surfaces later at runtime, when you attempt to open a compressed image, and Pillow realizes it lacks the necessary decoder.

2. The "How": Step-by-Step Solution​

To fix this, you must install the missing system library and then force Pillow to recompile so it can link to that library.

Step 1: Install Zlib Development Headers​

The command depends on your operating system.

Ubuntu / Debian / Linux Mint:

sudo apt-get update
sudo apt-get install zlib1g-dev

CentOS / RHEL / Fedora:

sudo yum install zlib-devel
# OR for newer Fedora versions
sudo dnf install zlib-devel

macOS (using Homebrew):

brew install zlib
xcode-select --install

Step 2: Reinstall Pillow (Crucial Step)​

Simply installing Zlib is not enough. You must reinstall Pillow so the build process can "see" the newly installed Zlib headers.

You must use the --no-cache-dir flag to prevent pip from using the previously cached (broken) wheel, and --force-reinstall to ensure the rebuild happens.

pip install --force-reinstall --no-cache-dir pillow

3. Special Case: Virtual Environments (Pyenv/Docker)​

If you are using pyenv or Docker, the order of operations is vital.

  1. Docker: Ensure your Dockerfile installs zlib1g-dev (and libjpeg-dev for JPEGs) before the RUN pip install -r requirements.txt step.
  2. Pyenv: If you are building a Python version from scratch, ensure Zlib is installed on the host OS before running pyenv install 3.x.x.

Summary Checklist​

ComponentStatusAction
System LibraryMissingRun sudo apt-get install zlib1g-dev (or OS equivalent).
Pillow PackageInstalled (Broken)Run pip install --force-reinstall --no-cache-dir pillow.
ResultFixedPillow can now decode PNG and Zip-compressed images.

Sources and Further Reading​