VMware ESXi and vSphere Cluster Management

How to Install Pillow

Learn how to install Pillow with pip or from a source archive on Windows, Linux, macOS, and FreeBSD, then verify it with Python.

What Is Pillow?

Pillow is a Python imaging library for opening, manipulating, and saving image files. You can use it to resize, crop, rotate, convert, and inspect images in Python programs.

The package name used with Python's package installer is Pillow. The library is usually imported through the PIL namespace, for example from PIL import Image. PIL refers to the import namespace commonly used by Pillow and is not the package name you install.

Supported Operating Systems

Pillow can be installed on Windows, Linux, macOS, and FreeBSD. The basic Python commands are similar on each system, but the terminal name, Python command, permissions, compiler tools, and package prerequisites can differ.

Operating System	Typical Shell	Recommended Installation Command Pattern	Common Consideration
Windows	Command Prompt or PowerShell	`py -m pip install Pillow` or `python -m pip install Pillow`	Several Python installations may exist; choose the interpreter used by the project.
Linux	Terminal and shell	`python3 -m pip install Pillow`	System Python may be managed by the operating system, so a virtual environment is recommended.
macOS	Terminal and shell	`python3 -m pip install Pillow`	Confirm that the command selects the Python installation used by the application.
FreeBSD	Terminal and shell	`python3 -m pip install Pillow`	Source builds may require additional ports or development tools.

Prerequisites

Before installing Pillow, make sure you have a supported Python installation and pip, Python's package installer. Prefer invoking pip through the selected Python interpreter rather than calling a standalone pip command. This reduces the chance of installing Pillow into a different Python installation.

Check the Python version:

python --version

On systems where Python 3 is invoked as python3, use:

python3 --version

Check whether pip is available for that interpreter:

python -m pip --version

On Linux, macOS, or FreeBSD, the equivalent may be:

python3 -m pip --version

On Windows, the Python launcher can select a Python installation explicitly:

py -m pip --version

Choose the Correct Python Environment

An active environment is the Python interpreter and package location currently selected by your shell or development tool. Pillow must be installed into the same environment that runs your application.

A virtual environment is an isolated Python environment for project-specific dependencies. It is the preferred location for Pillow because it avoids changing system-wide packages and helps keep projects independent.

Create and activate a virtual environment from your project directory with commands appropriate to your platform:

python -m venv .venv

On Windows PowerShell:

.venv\Scripts\Activate.ps1

On Windows Command Prompt:

.venv\Scripts\activate.bat

On Linux, macOS, or FreeBSD:

source .venv/bin/activate

After activation, use python -m pip so installation targets the active environment.

Install Pillow with pip

pip is the normal installation method. In the active environment, run:

python -m pip install Pillow

If your platform uses python3 for the desired interpreter, run:

python3 -m pip install Pillow

On Windows, you can use:

py -m pip install Pillow

Typical pip output includes several stages:

Collection: pip locates the requested Pillow package and compatible dependencies.
Wheel download or cache use: pip downloads a compatible wheel, or reuses one already stored in its cache. A wheel is a prebuilt Python package distribution that often avoids compiling code locally.
Installation: pip places the package into the selected Python environment.
Completion: a message such as Successfully installed Pillow indicates that the installation command completed successfully.

To upgrade an existing Pillow installation, use:

python -m pip install --upgrade Pillow

Installation Methods Compared

Method	When to Use It	Advantages	Considerations
pip installation	Normal project installation	Simple, reproducible, and usually able to use a compatible prebuilt wheel	Requires pip and a compatible Python environment.
Interpreter-specific pip installation	Multiple Python versions or environments are installed	Clearly targets the interpreter that will run the application	Use the correct interpreter command, such as `python3 -m pip` or `py -m pip`.
Source archive installation	pip-based installation is unavailable or a source build is specifically required	Installs from downloaded source code and can support unusual build requirements	May require compilers and image-library development dependencies; it is more complex than pip.

Verify the Installation

The most useful check is to import Pillow through the PIL namespace:

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

If the command prints a version number and exits without an import error, the selected Python interpreter can use Pillow.

You can also inspect pip's package record:

python -m pip show Pillow

This displays details such as the installed version, package location, and metadata.

Install from a Downloaded Source Archive

A source archive is a downloadable source distribution that must be built or installed locally. This method is an alternative to the preferred pip workflow and is generally used when a compatible wheel is unavailable or when a source build is required.

Download the Pillow source distribution using the distribution method provided for your project.
Extract the archive into a working directory.
Open a terminal in the extracted source directory.
Activate the virtual environment that should receive Pillow.
Run the legacy setup-based installation command:

python setup.py install

The command must be run from the directory containing setup.py. Because this is a legacy setup-based approach, prefer python -m pip install Pillow whenever pip can install a compatible package.

Source installation can require a C compiler, platform-specific build tools, and development versions of image-format or compression libraries. The exact requirements depend on the operating system, Python version, and Pillow features being built. If you do not specifically need a source build, a compatible pip wheel is usually easier.

Troubleshooting

“pip” is not recognized

This usually means Python or pip is not installed correctly, or the Python scripts directory is not on the system PATH. Try the interpreter-based form instead:

python -m pip install Pillow

If that also fails, verify the Python installation, confirm that the selected interpreter is available, and review the PATH configuration.

Pillow installs but cannot be imported

The application may be running under a different interpreter or virtual environment from the one used for installation. Compare the interpreter used to launch the application with the interpreter used to run pip. Then install Pillow through that same interpreter, for example:

python -m pip install Pillow

A source installation fails during the build

The system may be missing compiler tools or image-format and compression-library development dependencies. Prefer a compatible prebuilt wheel through pip. If a source build is required, install the platform-specific build tools and required development libraries, then retry.

Permission errors occur

The selected environment may be system-managed or not writable by your user account. Install Pillow in a project virtual environment. A user-level installation can also be appropriate in some environments, but it should not replace a project environment when isolation is needed.

Quick Installation Checklist

Confirm that a supported Python installation is available.
Check the version of the exact interpreter used by the project.
Check pip with python -m pip --version.
Activate the project's virtual environment when possible.
Run python -m pip install Pillow.
Verify with python -c "from PIL import Image; print(Image.__version__)".
If pip cannot provide a suitable package, consider a source archive and its build prerequisites.

For related work, continue with Pillow installation and setup guidance before using PIL.Image in an image-processing project.