Documentation Menu
Home / Reference / Integration Guide

Integration Guide

Independent practical guide. For canonical API reference see the official Pillow documentation.

Django

Django's ImageField depends on Pillow for image validation. For more advanced tasks like generating thumbnails or watermarking on upload, use Django signals or a dedicated library like django-imagekit.

Django: Process Upload
# models.py from django.db import models class Photo(models.Model): image = models.ImageField(upload_to="photos/") # signals.py — auto-generate thumbnail on upload from django.db.models.signals import post_save from PIL import Image import os def create_thumbnail(sender, instance, **kwargs): if instance.image: with Image.open(instance.image.path) as img: img.thumbnail((300, 300), Image.Resampling.LANCZOS) thumb_path = instance.image.path.replace("/photos/", "/thumbs/") img.save(thumb_path) post_save.connect(create_thumbnail, sender=Photo)

FastAPI

FastAPI's file upload handling works seamlessly with Pillow via UploadFile → BytesIO → Image.open().

FastAPI Image Upload Handler
from fastapi import FastAPI, UploadFile, File from fastapi.responses import StreamingResponse from PIL import Image import io app = FastAPI() @app.post("/resize") async def resize_image(file: UploadFile = File(...)): contents = await file.read() img = Image.open(io.BytesIO(contents)) img.thumbnail((800, 800), Image.Resampling.LANCZOS) buf = io.BytesIO() img.save(buf, format="WEBP", quality=85) buf.seek(0) return StreamingResponse(buf, media_type="image/webp")

Flask

Flask Upload + Process
from flask import Flask, request, send_file from PIL import Image import io app = Flask(__name__) @app.post("/convert") def convert(): file = request.files["image"] img = Image.open(file.stream).convert("RGB") buf = io.BytesIO() img.save(buf, "JPEG", quality=90) buf.seek(0) return send_file(buf, mimetype="image/jpeg")

NumPy

Pillow and NumPy arrays can be converted freely. This allows you to apply arbitrary mathematical operations on pixel data and then render back to an image.

Pillow ↔ NumPy
import numpy as np from PIL import Image # PIL → NumPy array img = Image.open("photo.jpg") arr = np.array(img) print(arr.shape) # (height, width, 3) for RGB # Apply NumPy operations inv = 255 - arr # invert all values # NumPy array → PIL Image result = Image.fromarray(inv.astype(np.uint8)) result.save("inverted.jpg")

PyTorch / torchvision (AI & Deep Learning)

PyTorch uses Pillow as its default image loader. torchvision.transforms natively operates directly on PIL Images for data augmentation and neural network preprocessing pipelines.

torchvision Data Augmentation & Tensor Pipeline
from torchvision import transforms from PIL import Image # 1. Training Augmentation Pipeline (PIL → Tensor) train_transform = transforms.Compose([ transforms.RandomResizedCrop(224, scale=(0.8, 1.0)), transforms.RandomHorizontalFlip(p=0.5), transforms.ColorJitter(brightness=0.2, contrast=0.2), transforms.ToTensor(), # PIL Image [0, 255] → FloatTensor [0.0, 1.0] transforms.Normalize( mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225] ) ]) pil_img = Image.open("training_sample.jpg") tensor = train_transform(pil_img) print(tensor.shape) # torch.Size([3, 224, 224]) # 2. Reverse: Tensor → PIL Image for inspection/saving to_pil = transforms.ToPILImage() reconstructed_img = to_pil(tensor) reconstructed_img.save("inspected.png")

OpenCV

OpenCV and Pillow use different colour channel orders. OpenCV is BGR, Pillow is RGB. You must convert when passing data between libraries.

Pillow ↔ OpenCV
import cv2 import numpy as np from PIL import Image # Pillow → OpenCV (RGB → BGR) pil_img = Image.open("photo.jpg") cv_img = cv2.cvtColor(np.array(pil_img), cv2.COLOR_RGB2BGR) # OpenCV → Pillow (BGR → RGB) cv_img = cv2.imread("photo.jpg") pil_img = Image.fromarray(cv2.cvtColor(cv_img, cv2.COLOR_BGR2RGB))

Tesseract OCR + OpenCV + Pillow Pipeline

The standard Python Computer Vision stack for document intelligence and OCR projects combines all three libraries:

  • OpenCV: High-speed image pre-processing (grayscale conversion, Otsu thresholding, noise removal).
  • Tesseract OCR (via pytesseract): the OCR engine that extracts text and per-word bounding boxes from a Pillow image. To try OCR on a sample image without installing anything, there is a browser demo at tesseractocr.org (a sister site).
  • Pillow: High-fidelity TrueType text overlays, bounding box annotations (ImageDraw), and final multi-format export.
Pillow + OpenCV + Tesseract OCR Pipeline
import cv2 import numpy as np import pytesseract from PIL import Image, ImageDraw, ImageFont # Step 1: Pre-process with OpenCV (Grayscale + Adaptive Otsu Thresholding) cv_img = cv2.imread("receipt.png") gray = cv2.cvtColor(cv_img, cv2.COLOR_BGR2GRAY) thresh = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY | cv2.THRESH_OTSU)[1] # Step 2: Extract text and bounding boxes with PyTesseract ocr_data = pytesseract.image_to_data(thresh, output_type=pytesseract.Output.DICT) # Step 3: Convert OpenCV array back to Pillow Image for annotation pil_img = Image.fromarray(cv2.cvtColor(cv_img, cv2.COLOR_BGR2RGB)) draw = ImageDraw.Draw(pil_img) for i in range(len(ocr_data["text"])): confidence = int(ocr_data["conf"][i]) text = ocr_data["text"][i].strip() if confidence > 50 and text: x, y, w, h = ocr_data["left"][i], ocr_data["top"][i], ocr_data["width"][i], ocr_data["height"][i] # Draw bounding box draw.rectangle([x, y, x + w, y + h], outline="lime", width=2) # Overlay detected label draw.text((x, max(0, y - 14)), text, fill="lime") pil_img.save("ocr_annotated.png")

Tkinter

Tkinter's native PhotoImage only supports GIF and PGM. Use ImageTk.PhotoImage from Pillow to display any image format in a Tkinter window.

Tkinter Display
import tkinter as tk from PIL import Image, ImageTk root = tk.Tk() img = Image.open("photo.jpg").resize((400, 300)) photo = ImageTk.PhotoImage(img) label = tk.Label(root, image=photo) label.pack() root.mainloop()

Qt (PyQt5 / PySide6)

Convert Pillow images to Qt's QImage via NumPy as an intermediate layer.

Pillow → QImage
from PyQt5.QtGui import QImage, QPixmap from PIL import Image import numpy as np img = Image.open("photo.jpg").convert("RGBA") data = np.array(img) h, w, ch = data.shape qimage = QImage(data.tobytes(), w, h, ch * w, QImage.Format_RGBA8888) pixmap = QPixmap.fromImage(qimage)