{"id":3308,"library":"uhashring","title":"uhashring Consistent Hashing Library","description":"uhashring is a full-featured pure Python library for consistent hashing, primarily used in distributed systems, caches, and databases to efficiently distribute data across nodes. It aims to prevent total reshuffling of key-node mappings when nodes are added or removed. The library offers Ketama compatibility, customizable hash and weight functions, and supports instance-oriented usage. The current version is 2.4, with releases occurring periodically, as evidenced by its PyPI update in April 2025 and ongoing GitHub activity. [1, 2]","status":"active","version":"2.4","language":"en","source_language":"en","source_url":"https://github.com/ultrabug/uhashring","tags":["hashing","consistent-hashing","ketama","distributed-systems","cache"],"install":[{"cmd":"pip install uhashring","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"symbol":"HashRing","correct":"from uhashring import HashRing"}],"quickstart":{"code":"from uhashring import HashRing\n\n# Initialize a consistent hash ring with nodes\nhr = HashRing(nodes=['node1', 'node2', 'node3'])\n\n# Get the node responsible for a given key\nkey_to_find = \"my_data_key\"\nresponsible_node = hr.get_node(key_to_find)\nprint(f\"Key '{key_to_find}' maps to node: {responsible_node}\")\n\n# Add a new node with a custom weight\nhr.add_node('node4', {'weight': 10})\n\n# Remove a node\nhr.remove_node('node2')\n\n# Get the distribution of keys across nodes (after changes)\n# Note: This is an example, actual distribution varies with keys and hash function.\n# For a real application, you'd query 'get_node' for many keys to see the effect.\nprint(\"Current node configuration:\", hr.conf)\nprint(\"Node distribution (example property, not a real-time key distribution):\")\n# The 'distribution' property is a Counter of how many points each node occupies on the ring.\nprint(hr.distribution)\n","lang":"python","description":"This quickstart demonstrates how to initialize a `HashRing` with a list of nodes, find the responsible node for a specific key, and dynamically add or remove nodes. It also shows how to check the current configuration and the distribution of 'points' on the ring among the nodes. [1, 2]"},"warnings":[{"fix":"For Ketama compatibility, explicitly initialize `HashRing(hash_fn='ketama', vnodes=40, replicas=4, ...)` to restore the previous behavior. Otherwise, be aware of the new default hashing algorithm and vnode count. [1]","message":"Since v1.0, the default hash function changed from 'ketama' to 'md5', and the default number of vnodes per node increased from 40 to 160. This change was made for linear performance on node changes but breaks compatibility with older setups relying on the Ketama default. [1]","severity":"breaking","affected_versions":">=1.0"},{"fix":"Ensure your project runs on Python 3.8 or newer. If Python 2 support is critical, you must use `uhashring==1.1.0` (or `uhashring==1.2` for the last version with Py2 support, but newer features might be missing). [1]","message":"Python 2 support was dropped. `uhashring` versions 1.2 and newer do not support Python 2. [1]","severity":"deprecated","affected_versions":">=1.2"},{"fix":"Consider if strict Ketama compatibility is necessary. For better performance on dynamic node topology, rely on the default MD5 hash function or use another custom hash function that doesn't require full ring regeneration. [1]","message":"When using `hash_fn='ketama'`, adding or removing nodes requires a complete ring regeneration, which can degrade performance in rapidly changing environments. The default MD5 implementation provides linear performance for these operations. [1]","severity":"gotcha","affected_versions":"All versions"},{"fix":"Carefully design and test your `weight_fn` if you choose to implement one. Ensure it accurately reflects the capacity or desired load of each node. [1]","message":"Custom node weights significantly influence key distribution. Incorrectly configured weights can lead to uneven load distribution or 'hotspots' on specific nodes. [1]","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}