Install & Compatibility
Where this runs
tested against v1.1.5 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.940 runs
installs and imports cleanly · install 0.0s · import 0.000s · 92.2MB
glibcpy 3.10–3.940 runs
installs and imports cleanly · install 1.8s · import 0.000s · 18MB
83MB installed
● package 83MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
encode
✓ from blurhash import encode
Used to generate a blurhash string from image pixel data.
decode
✓ from blurhash import decode
Used to reconstruct a blurred image (pixel data) from a blurhash string.
This quickstart demonstrates how to encode an image into a BlurHash string and then decode that string back into a blurred image. It uses Pillow for image creation and manipulation, showing how to prepare pixel data for the `blurhash` library's `encode` function, which expects a flat list of RGBA values.
import os
from PIL import Image
from blurhash import encode, decode
# 1. Create a dummy image for demonstration
width, height = 32, 32
img = Image.new('RGBA', (width, height), color = 'red')
img.putpixel((0, 0), (0, 255, 0, 255)) # Green pixel at top-left
img.putpixel((width-1, height-1), (0, 0, 255, 255)) # Blue pixel at bottom-right
# Prepare image data for blurhash (flat list of RGBA values)
# The library expects pixel data as a flat list, not a Pillow Image object directly.
# If your image is RGB, you might need to convert it to RGBA first.
pixel_data = []
for y in range(height):
for x in range(width):
r, g, b, a = img.getpixel((x, y))
pixel_data.extend([r, g, b, a])
# 2. Encode the image
x_components = 4 # How many color components horizontally
y_components = 3 # How many color components vertically
blurhash_string = encode(pixel_data, width, height, x_components, y_components)
print(f"Generated BlurHash: {blurhash_string}")
# 3. Decode the blurhash string back into pixel data
output_width = 160
output_height = 90
decoded_pixels = decode(blurhash_string, output_width, output_height)
# 4. Reconstruct image from decoded pixels (using Pillow)
decoded_img = Image.new('RGBA', (output_width, output_height))
decoded_img.putdata(list(zip(*[iter(decoded_pixels)]*4)))
# 5. Save the original and decoded images
original_path = 'original_image.png'
decoded_path = 'decoded_blurhash.png'
img.save(original_path)
decoded_img.save(decoded_path)
print(f"Original image saved to {original_path}")
print(f"Decoded blurhash image saved to {decoded_path}")
# Clean up (optional)
# os.remove(original_path)
# os.remove(decoded_path)
Errors
Common errors & fixes
ValueError: Image data is not in the expected format (width * height * 4 required)
The `encode` function received a pixel data list whose length does not match `width * height * 4`. This often happens if the input image was RGB (3 channels) but the function expects RGBA (4 channels) implicitly, or if the width/height parameters are incorrect for the provided data.
fixEnsure your `pixel_data` list contains `width * height * 4` elements, where 4 accounts for R, G, B, and A channels. If your source image is RGB, you might need to convert it to RGBA before flattening the pixel data (e.g., `img.convert('RGBA')` with Pillow). IndexError: tuple index out of range (when using img.putpixel or similar in reconstruction)
This error typically occurs when trying to reconstruct an image from decoded pixel data if the `width` and `height` provided to `decode` do not result in a pixel array that can be correctly mapped to an image of those dimensions. It can also happen if `decoded_pixels` length isn't a multiple of 4 (for RGBA).
fixVerify that the `width` and `height` passed to `decode` are correct and that the resulting `decoded_pixels` list has a length of `width * height * 4`. When using `putdata` with Pillow, ensure the list of tuples is correctly formed, i.e., `list(zip(*[iter(decoded_pixels)]*4))` for RGBA.
TypeError: encode() missing 2 required positional arguments: 'width' and 'height'
The `encode` function requires the `pixel_data` list, `width`, `height`, `x_components`, and `y_components` as arguments. This error means `width` and `height` were omitted.
fixAlways provide the correct `width` and `height` of the original image whose pixel data you are passing to the `encode` function: `encode(pixel_data, image_width, image_height, x_components, y_components)`.
Upgrade
Version history
1.1.5latest on PyPI · released Aug 17, 2025
Audit
Dependencies
No dependency data recorded yet.