{"id":7990,"library":"blurhash","title":"Blurhash Python Library","description":"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.","status":"active","version":"1.1.5","language":"en","source_language":"en","source_url":"https://github.com/halcy/blurhash-python","tags":["image processing","utility","blurhash","encoding","decoding","placeholder"],"install":[{"cmd":"pip install blurhash","lang":"bash","label":"Install core library"},{"cmd":"pip install Pillow","lang":"bash","label":"Install Pillow (for image handling in quickstart)"}],"dependencies":[],"imports":[{"note":"Used to generate a blurhash string from image pixel data.","symbol":"encode","correct":"from blurhash import encode"},{"note":"Used to reconstruct a blurred image (pixel data) from a blurhash string.","symbol":"decode","correct":"from blurhash import decode"}],"quickstart":{"code":"import os\nfrom PIL import Image\nfrom blurhash import encode, decode\n\n# 1. Create a dummy image for demonstration\nwidth, height = 32, 32\nimg = Image.new('RGBA', (width, height), color = 'red')\nimg.putpixel((0, 0), (0, 255, 0, 255)) # Green pixel at top-left\nimg.putpixel((width-1, height-1), (0, 0, 255, 255)) # Blue pixel at bottom-right\n\n# Prepare image data for blurhash (flat list of RGBA values)\n# The library expects pixel data as a flat list, not a Pillow Image object directly.\n# If your image is RGB, you might need to convert it to RGBA first.\npixel_data = []\nfor y in range(height):\n    for x in range(width):\n        r, g, b, a = img.getpixel((x, y))\n        pixel_data.extend([r, g, b, a])\n\n# 2. Encode the image\nx_components = 4 # How many color components horizontally\ny_components = 3 # How many color components vertically\nblurhash_string = encode(pixel_data, width, height, x_components, y_components)\nprint(f\"Generated BlurHash: {blurhash_string}\")\n\n# 3. Decode the blurhash string back into pixel data\noutput_width = 160\noutput_height = 90\n\ndecoded_pixels = decode(blurhash_string, output_width, output_height)\n\n# 4. Reconstruct image from decoded pixels (using Pillow)\ndecoded_img = Image.new('RGBA', (output_width, output_height))\ndecoded_img.putdata(list(zip(*[iter(decoded_pixels)]*4)))\n\n# 5. Save the original and decoded images\noriginal_path = 'original_image.png'\ndecoded_path = 'decoded_blurhash.png'\nimg.save(original_path)\ndecoded_img.save(decoded_path)\nprint(f\"Original image saved to {original_path}\")\nprint(f\"Decoded blurhash image saved to {decoded_path}\")\n\n# Clean up (optional)\n# os.remove(original_path)\n# os.remove(decoded_path)\n","lang":"python","description":"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."},"warnings":[{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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).","cause":"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.","error":"ValueError: Image data is not in the expected format (width * height * 4 required)"},{"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.","cause":"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).","error":"IndexError: tuple index out of range (when using img.putpixel or similar in reconstruction)"},{"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)`.","cause":"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.","error":"TypeError: encode() missing 2 required positional arguments: 'width' and 'height'"}]}