Pages

Topics

Tools

↑↓navigate↵openescclose
All guides

Python Pillow: Grayscale, Blur, Sharpen, and Image Filters

Use Pillow's ImageFilter module to convert images to grayscale, apply Gaussian or box blur, sharpen images, and run built-in edge-detection filters. Includes Python examples.

~4 min readPython
#Pillow#Image Processing#Grayscale#Blur
A 2x2 grid showing the same landscape photo in original color, grayscale, blurred, and sharpened versions to illustrate Pillow image filters.

Pillow's ImageFilter module provides the main API for image filters in Python. Use Image.convert() with mode "L" to make a grayscale version of an image, and use Image.filter() with a filter such as GaussianBlur, UnsharpMask, or FIND_EDGES to blur, sharpen, or detect edges.

The examples below show the core operations, how to combine them, and what to keep in mind when processing large images.

Converting Images to Grayscale with Pillow

The simplest way to convert an image to grayscale is img.convert("L"). The "L" mode creates an 8-bit grayscale image where each pixel has a single luminance value.

python
from PIL import Image img = Image.open("photo.jpg") gray = img.convert("L") gray.save("photo_gray.jpg")

If the source image has transparency and you want to keep it, use "LA" instead. "LA" represents grayscale pixels with an alpha channel.

Applying Gaussian and Box Blur

ImageFilter includes GaussianBlur and BoxBlur, both of which accept a radius parameter to control blur intensity.

python
from PIL import Image, ImageFilter img = Image.open("photo.jpg") gaussian = img.filter(ImageFilter.GaussianBlur(radius=2)) gaussian.save("gaussian.jpg") box = img.filter(ImageFilter.BoxBlur(radius=3)) box.save("box.jpg")

GaussianBlur produces a smooth, soft result. BoxBlur averages pixels in a square region, so it is convenient for quick previews and can be faster, but very high radius values may look blocky. For most image-processing work, GaussianBlur is the safer choice when visual quality matters.

The radius parameter is a float. A value such as 1.5 gives finer control, and 0 leaves the image unchanged.

Sharpening Images with ImageFilter

Pillow has two built-in sharpening options: SHARPEN and UnsharpMask. SHARPEN applies a fixed convolution kernel that increases contrast around edges. UnsharpMask gives more control through radius, percent, and threshold.

python
from PIL import Image, ImageFilter img = Image.open("photo.jpg") sharpened = img.filter(ImageFilter.SHARPEN) sharpened.save("sharpen.jpg") unsharp = img.filter(ImageFilter.UnsharpMask(radius=2, percent=150, threshold=3)) unsharp.save("unsharp.jpg")

The unsharp mask technique subtracts a blurred copy of the image from the original and then scales the difference. radius controls how wide the effect is, percent controls the amount of sharpening, and threshold limits sharpening to pixels whose contrast exceeds a minimum value. A higher threshold leaves low-contrast areas untouched and helps avoid amplifying noise.

For a subtle starting point, use radius=1, percent=100, and threshold=3, then increase percent until the result looks right.

Using Built-in Filters: Edge Detection, Emboss, and More

The ImageFilter module also includes predefined filters for edge detection and artistic effects, including FIND_EDGES, EDGE_ENHANCE, EMBOSS, CONTOUR, and SMOOTH.

python
from PIL import Image, ImageFilter img = Image.open("photo.jpg") edges = img.filter(ImageFilter.FIND_EDGES) edges.save("edges.jpg") emboss = img.filter(ImageFilter.EMBOSS) emboss.save("emboss.jpg")

FIND_EDGES highlights rapid changes in intensity and produces a black-and-white edge map. EMBOSS gives the image a raised, metallic appearance. These filters use fixed convolution kernels, so they are fast but not customizable.

If you need a custom convolution kernel, use ImageFilter.Kernel with a matrix. For example, this 3x3 kernel detects edges:

python
from PIL import Image, ImageFilter img = Image.open("photo.jpg") kernel = ImageFilter.Kernel( size=(3, 3), kernel=[-1, -1, -1, -1, 8, -1, -1, -1, -1], scale=1, offset=0, ) edges = img.filter(kernel) edges.save("custom_edges.jpg")

The scale parameter divides the convolution result, and offset is added to each output pixel.

Combining Filters for a Custom Effect

You can chain filters to get a result that no single filter would produce. For example, convert to grayscale and then detect edges for a sketch-like effect, or blur first to reduce noise and then sharpen to restore edges.

python
from PIL import Image, ImageFilter img = Image.open("photo.jpg") gray = img.convert("L") sketch = gray.filter(ImageFilter.FIND_EDGES) sketch.save("sketch.jpg") blurred = img.filter(ImageFilter.GaussianBlur(radius=1)) restored = blurred.filter(ImageFilter.UnsharpMask(radius=2, percent=120, threshold=2)) restored.save("restored.jpg")

Because each filter() call returns a new image, chaining filters creates temporary image objects. For large images this can increase memory use. If possible, replace several filter calls with a single custom kernel that captures the combined effect in one pass.

Performance and Memory Considerations for Large Images

Filtering is CPU-bound, and every pass over a large image takes time. A 4000x3000 image has 12 million pixels, so batch jobs can become slow.

  • Use one Image.filter() call rather than chaining many simple filters when possible.
  • For blur, BoxBlur is often fast enough for previews and can be faster than GaussianBlur when the exact Gaussian falloff is not required.
  • Process files in a loop and use with blocks so file handles close promptly.
python
from PIL import Image, ImageFilter for filename in ["a.jpg", "b.jpg", "c.jpg"]: with Image.open(filename) as img: processed = img.filter(ImageFilter.GaussianBlur(radius=2)) processed.save(f"blurred_{filename}")

Intermediate images become eligible for garbage collection when they go out of scope. For very large batches, you can delete references explicitly or split the work across processes with multiprocessing.

Choosing the Right Filter for Your Use Case

The best filter depends on the goal. A quick preview can use BoxBlur with a small radius. A photo edit that needs careful tuning benefits from GaussianBlur and UnsharpMask.

FilterUse caseSpeedControl
GaussianBlurSmooth, natural blurMediumHigh
BoxBlurFast blur for previewsFastLow
SHARPENQuick sharpening without parametersFastLow
UnsharpMaskPrecise sharpening with thresholdSlowHigh
FIND_EDGESEdge detection for vision tasksFastNone
KernelCustom convolutionVariesFull

If you apply the same custom kernel to many images, create the Kernel object once and reuse it.

Before running a large batch, test the filters on representative samples. The best radius or threshold can vary with image content, so a fixed set of parameters may not work for every image.

Try matching browser tools

All tools

Small utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.

All Python guides

More in Python

All Python guides

The guides filed next to this one in Python, in library order.