Introduction

The original PIL project is no longer maintained, so installing PIL directly with pip usually fails on modern macOS. The supported replacement is Pillow, which provides a compatible import path through from PIL import .... A reliable installation on Mac depends on matching Python environment, pip binary, and native library dependencies.

Use Pillow Instead of Legacy PIL

If you run pip install PIL, pip will not find a current package. Use Pillow and keep the PIL import namespace in your code.

python3 -m pip install --upgrade pip
python3 -m pip install Pillow

Verify the install:

python3 -c "from PIL import Image; print(Image.__version__)"

This command should print a Pillow version and exit without errors.

Install in a Virtual Environment

On macOS, using a virtual environment avoids conflicts with system Python and Homebrew Python packages.

1python3 -m venv .venv
2source .venv/bin/activate
3python -m pip install --upgrade pip
4python -m pip install Pillow

Then run a quick smoke test.

1from PIL import Image, ImageOps
2
3img = Image.new("RGB", (120, 80), color="navy")
4img = ImageOps.expand(img, border=4, fill="white")
5img.save("sample.png")
6print("saved sample.png")

If sample.png appears, installation and basic image operations are working.

Handle Native Dependency Issues on macOS

Some Pillow features depend on libraries such as libjpeg, zlib, and freetype. If wheel resolution fails and pip tries source build, install common dependencies with Homebrew first.

brew update
brew install jpeg zlib freetype little-cms2 webp

Then reinstall Pillow in the active environment:

python -m pip uninstall -y Pillow
python -m pip install --no-cache-dir Pillow

Most users get prebuilt wheels, but this fallback helps on unusual architectures or pinned older versions.

Confirm Correct Python and pip Pairing

A frequent macOS issue is installing packages with one interpreter and running code with another. Always pair pip with the exact interpreter using python -m pip.

which python3
python3 --version
python3 -m pip --version

If your editor uses a different interpreter, select the same virtual environment there too.

Migrate Old PIL Code Safely

Many old codebases already import PIL. In most cases, only installation changes are required. API names are largely compatible, but check release notes when upgrading across large version gaps.

1from PIL import Image
2
3with Image.open("sample.png") as im:
4    print(im.mode, im.size)

This code works with Pillow and keeps legacy import style intact.

Troubleshoot Build and Import Errors

If installation succeeds but imports fail, inspect the active interpreter path and site packages location. This quickly reveals whether your shell and editor are using different Python runtimes.

python -c "import sys; print(sys.executable)"
python -c "import site; print(site.getsitepackages())"
python -c "import PIL, pathlib; print(pathlib.Path(PIL.__file__).resolve())"

For reproducible team setups, pin Pillow in a requirements file:

Pillow==11.0.0

Pinned versions reduce surprise upgrades that may change image codec behavior across developer machines.

Common Pitfalls

A common mistake is running pip install PIL and assuming package mirrors are broken. The project is simply deprecated and replaced by Pillow.

Another issue is installing Pillow globally, then running code inside a virtual environment that does not have it. Verify active environment before installation.

A third issue is architecture mismatch on Apple Silicon, where terminal runs one Python build and editor runs another. Keep one consistent interpreter path.

Summary

• Install Pillow, not legacy PIL, on modern macOS.
• Use python -m pip so pip matches the runtime interpreter.
• Prefer virtual environments for stable package isolation.
• Install native dependencies only if wheel installation fails.
• Validate with a short script that creates and saves an image.
• Treat Pillow as the maintained drop-in replacement and avoid chasing the old PIL package name.