pythonware.com products ::: library ::: search ::: daily Python-URL!

Library

Python Imaging Library Handbook :::

A Django site.
   

Python Imaging Library Handbook

Next

This is the PIL handbook, last updated May 6, 2005. This edition covers release 1.1.5 of the Python Imaging Library.

You can find versions in other formats, as well as earlier versions, in the PythonWare library.

 

Part I. Introduction

Overview
Tutorial
Concepts

Part II. Module Reference

The Image Module
The ImageChops Module
The ImageColor Module
The ImageDraw Module
The ImageEnhance Module
The ImageFile Module
The ImageFileIO Module
The ImageFilter Module
The ImageFont Module
The ImageGrab Module
The ImageMath Module (PIL 1.1.6 only)
The ImageOps Module
The ImagePalette Module
The ImagePath Module
The ImageQt Module (PIL 1.1.6 only)
The ImageSequence Module
The ImageStat Module
The ImageTk Module
The ImageWin Module
The PSDraw Module

The ImageCrackCode Module
The ImageGL Module

Part III. Tools Reference

The pildriver Script
The pilconvert Script
The pilfile Script
The pilfont Script
The pilprint Script

Appendixes

Software License
Support
Image File Formats

BMP
BUFR (identify only)
CUR (read only)
DCX (read only)
EPS (write-only)
FITS (identify only)
FLI, FLC (read only)
FPX (read only)
GBR (read only)
GD (read only)
GIF
GRIB (identify only)
HDF5 (identify only)
ICO (read only)
IM
IMT (read only)
IPTC/NAA (read only)
JPEG
MCIDAS (read only)
MIC (read only)
MPEG (identify only)
MSP
PALM (write only)
PCD (read only)
PCX
PDF (write only)
PIXAR (read only)
PNG
PPM
PSD (read only)
SGI (read only)
SPIDER
TGA (read only)
TIFF
WAL (read only)
WMF (identify only)
XBM
XPM (read only)
XV Thumbnails
Writing Your Own File Decoder

Next


The Python Imaging Library (PIL) adds image processing capabilities to your Python interpreter. This library provides extensive file format support, an efficient internal representation, and fairly powerful image processing capabilities. The core image library is designed for fast access to data stored in a few basic pixel formats. It should provide a solid foundation for a general image processing tool.

By providing a standardized interface for manipulating images, PIL has become a staple for Python developers working with graphics. While the original PIL project stopped official updates years ago, its legacy lives on through the Pillow project—a modern, user-friendly fork that remains the industry standard for image manipulation in Python today.

If you've ever written a Python script that automatically resized a batch of vacation photos, or if you have worked on a machine learning model that "sees" objects, you have likely shaken hands with the Python Imaging Library (PIL). It is one of those foundational tools that sits quietly in the background, doing the heavy lifting while more famous libraries take the spotlight.

In this guide, we are going to look past the code and explore why this library became the gold standard for anyone handling pixels in Python.

What Exactly is PIL?

At its core, PIL is the bridge between raw data and visual imagery. Computers do not "see" a sunset; they see a massive grid of numbers representing colors. PIL gives Python the vocabulary to talk to those numbers. Whether you’re dealing with a JPEG from a high-end camera or a transparent PNG for a website, PIL treats them all with a unified logic.

The Magic of the "Image" Object

The genius of the library lies in the Image object. Instead of forcing you to understand complex binary file structures, PIL loads a file into an object that you can manipulate like clay. Want to flip it? There is a method for that. Want to turn it black and white? It is just one line of code. This abstraction is what made Python so accessible to non-engineers and artists alike.

Key Features You will Actually Use

  • Format Conversion: Think of it as a universal translator. You can open a TIFF and save it as a WebP without needing to know a single thing about how those formats work internally.
  • Geometric Wizardry: Resizing, rotating, and cropping are the "bread and butter" of PIL. It handles the math of interpolating pixels so your images don't look like a blurry mess when you scale them.
  • Enhancement: Sometimes an image just needs a bit more "pop." The library includes tools to tweak brightness, contrast, and sharpness, acting like a programmable version of Photoshop.

PIL vs. Pillow: A Tale of Two Names

If you try to install "PIL" today, you might get a bit confused. The original project (PIL) was the pioneer, but it eventually stopped receiving updates. The community, refusing to let such a vital tool die, created Pillow. It is a "friendly fork" that kept the original spirit alive while adding support for modern Python versions and faster processing. Today, when people say "PIL," they almost always mean "Pillow."

The Bottom Line

We live in a visual world. From social media filters to medical imaging, the demand for automated image handling is only growing. The Python Imaging Library proved that you don't need a PhD in computer graphics to build something beautiful. It turned pixels into something we can play with, and that is why it remains the first library many developers reach for when they have a vision to bring to life.