{"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":"python","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,"search_vec":"'1.1.5':46 'algorithm':16 'allow':17 'blur':29 'blurhash':1,5,15,63 'chang':59 'code':58 'compact':21 'core':57 'creat':20 'current':43 'decod':65 'distribut':53 'encod':64 'hash':23 'imag':25,38,60 'implement':12 'infrequ':50 'lazi':36 'lazy-load':35 'librari':3,6 'load':37 'occur':49 'placehold':30,66 'primarili':51 'process':61 'pure':10 'pure-python':9 'python':2,11 'rather':55 'releas':48 'repres':27 'uniqu':22 'updat':54 'use':33 'util':62 'version':44 'web':41","created_at":"2026-04-16T16:59:51.769767+00:00","updated_at":"2026-04-16T16:59:51.769767+00:00","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'"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"1.1.5","cli_name":"","cli_version":null,"type":"library","homepage":"https://blurhash.com","github":"https://github.com/halcy/blurhash-python","docs":null,"changelog":null,"pypi":"https://pypi.org/project/blurhash/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-28","last_verified":"2026-06-28","next_check":"2026-07-28","install_tag":null}}