Pillow in Python
Install Pillow, import it under its old name, and do the five jobs most scripts need.
Pillow is the library nearly every Python project uses to open, change and save images. If you searched for "pillow python" because an import failed, the fix is in the next section. If you want a quick tour, the rest of the page covers the five jobs that make up most image scripts.
The short answer
Install it as pillow, import it as PIL:
pip install pillow
from PIL import Image
img = Image.open("photo.jpg")
print(img.size) # (1200, 800)
print(img.mode) # RGB
print(img.format) # JPEG
The two names are the whole source of confusion. PIL, the Python Imaging Library, was the original package and stopped being updated in 2011. Pillow is the fork that took over. It kept the PIL import name so existing code carried on working, which is why the name you install and the name you import do not match.
Python image library install: pip and the PIL error
Whether you searched for "pip install python image library" or "python image library install", the command is the same one: pip install pillow. These are the mistakes that go with it:
pip install PILfails. There is no package by that name on PyPI. Installpillow.import pillowfails. The module is calledPIL, in capitals.ModuleNotFoundError: No module named 'PIL'after you have installed it almost always means pip put Pillow into a different Python from the one running your script. Runpython -m pip install pillowwith the samepythonyou use to run the script, or activate your virtual environment first.
To check what you have:
import PIL
print(PIL.__version__) # 12.1.0
Your number will differ. Anything from 10 onwards matches the examples on this page.
A short Python Pillow tutorial: the five common jobs
Open and inspect
Image.open is lazy. It reads the file header, so size, mode and format are available straight away, and the pixels are only decoded when you first need them. size is always (width, height).
Resize
resize takes the new size as a tuple and returns a new image. It does exactly what you ask, so it will squash the picture if the proportions differ. thumbnail shrinks an image to fit inside a box and keeps the proportions, but it changes the image in place, so copy first if you still need the original:
half = img.resize((600, 400))
thumb = img.copy()
thumb.thumbnail((400, 400))
print(thumb.size) # (400, 267)
There is more on filters, aspect ratio and whole folders in resize an image.
Crop
crop takes one tuple of four numbers: left, upper, right, lower. The last two are coordinates, not a width and height.
cropped = img.crop((200, 150, 1000, 650))
print(cropped.size) # (800, 500)
Centre crops, squares and fixed aspect ratios are covered in crop an image.
Convert format
Pillow picks the output format from the file extension, so converting is usually just saving under a new name:
img.save("photo.png")
img.save("photo.webp")
The one catch is transparency. JPEG has no alpha channel, so saving a transparent PNG as a JPEG raises OSError: cannot write mode RGBA as JPEG. Convert it to RGB first:
logo = Image.open("logo.png")
print(logo.mode) # RGBA
logo.convert("RGB").save("logo.jpg")
Save with quality
For JPEG and WebP, quality trades file size against detail on a scale from 0 to 100:
img.save("photo-web.jpg", quality=85, optimize=True)
img.save("photo-web.webp", quality=80)
JPEG defaults to 75 if you leave it out. Somewhere between 80 and 85 is a sensible setting for photos on the web, and going above 95 mostly makes the file bigger without looking any better. PNG is lossless, so quality does nothing there.
The shorter way with Nitro Image
Nitro Image is a wrapper around Pillow that turns those steps into one chain. It has its own class called Image, so in a file that also uses Pillow, import it under another name:
from nitro_img import Image as NitroImage
NitroImage("photo.jpg").resize(800).webp(quality=80).save("photo-800.webp")
resize(800) works out the height for you, and nothing is decoded or written until save runs. It is worth having when you produce web images in several sizes and formats. For opening one file and saving it once, Pillow alone is fine, and Nitro Image installs Pillow anyway, so nothing you learned here goes to waste.
Common questions
Is PIL the same as Pillow? In practice, yes. The original PIL is long dead, and every from PIL import ... you see today is running Pillow.
Can I have PIL and Pillow installed together? No. They use the same PIL folder and break each other. If an old machine still has the original, uninstall it before installing Pillow.
Why does import Image not work? Very old tutorials import it that way. With Pillow it is always from PIL import Image.
Which formats can Pillow read? JPEG, PNG, GIF, WebP, TIFF, BMP and a long list of less common ones, out of the box. AVIF and HEIC depend on your Pillow version or an extra plugin package.
This page uses Nitro Image.
Resize, convert, and optimise images with a chainable API. Generate responsive sizes in one call.
$ pip install nitro-image