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.

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.
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.
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.
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.
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:
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.
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,
BoxBluris often fast enough for previews and can be faster thanGaussianBlurwhen the exact Gaussian falloff is not required. - Process files in a loop and use
withblocks so file handles close promptly.
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.
| Filter | Use case | Speed | Control |
|---|---|---|---|
GaussianBlur | Smooth, natural blur | Medium | High |
BoxBlur | Fast blur for previews | Fast | Low |
SHARPEN | Quick sharpening without parameters | Fast | Low |
UnsharpMask | Precise sharpening with threshold | Slow | High |
FIND_EDGES | Edge detection for vision tasks | Fast | None |
Kernel | Custom convolution | Varies | Full |
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 toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.