Registry / serialization / blurhash

blurhash

JSON →
library1.1.5pypypi✓ verified 85d ago

The `blurhash` library is a pure-Python implementation of the BlurHash algorithm, allowing you to create compact, unique hashes for images that represent a blurred placeholder. This is useful for lazy-loading images on the web. The current version is 1.1.5, with releases occurring infrequently, primarily for distribution updates rather than core code changes.

pip install blurhash
INSTALL
IMPORT
SIG · BLURHASH
B
blurhash
serializationpythonv1.1.5
Install
1.8s avg
Import
Disk
83MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
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
musl
py 3.103.940 runs
installs and imports cleanly · install 0.0s · import 0.000s · 92.2MB
glibc
py 3.103.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)
Debug
Known issues
gotchaThe `encode` function expects raw pixel data as a flat list of RGBA integers, not a Pillow `Image` object or a NumPy array directly. You must manually extract and flatten the pixel data.
fix
Iterate through your image pixels (e.g., using `Pillow.Image.getpixel`) and collect them into a single list of `[R, G, B, A, R, G, B, A, ...]` integers.
affects: >=1.0.0
gotchaWhen calling `encode`, the `x_components` and `y_components` parameters determine the detail level of the blurhash. Using very low values (e.g., 1 or 2) can result in a highly pixelated or blocky hash that might not adequately represent the original image, while very high values increase the hash string's length without much visual gain.
fix
Experiment with values like `x_components=4`, `y_components=3` or `x_components=5`, `y_components=4`. The official BlurHash recommendation is typically between 3 and 9 components for both axes. Ensure `x_components >= 1` and `y_components >= 1`.
affects: >=1.0.0
gotchaThe `decode` function reconstructs pixel data for a specified output `width` and `height`. If these dimensions are significantly different from the *aspect ratio* of the original image that generated the blurhash, the decoded blurred image might appear stretched or distorted.
fix
Always attempt to decode using dimensions that maintain the original image's aspect ratio. If the original image was `160x90`, decoding to `320x180` will look correct, but decoding to `320x90` will stretch it.
affects: >=1.0.0
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.
fix
Ensure 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).
fix
Verify 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.
fix
Always 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.

Agent activity
20 hits · last 30 days
node
18
OpenAI (training)
1
Resources
blurhash — pip install blurhash · libregistry