uhashring

library2.5pypypi✓ verified 27d ago

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]

database data

pip install uhashring

github ↗package ↗

INSTALL

IMPORT

SIG · UHASHRING

uhashring

databasepythonv2.5

Install

1.5s avg

Import

10ms

Disk

16MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v2.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.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.008s · 17.8MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.5s · import 0.008s · 18MB

16MB installed

● package 16MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

HashRing

✓ from uhashring import HashRing

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]

from uhashring import HashRing # Initialize a consistent hash ring with nodes hr = HashRing(nodes=['node1', 'node2', 'node3']) # Get the node responsible for a given key key_to_find = "my_data_key" responsible_node = hr.get_node(key_to_find) print(f"Key '{key_to_find}' maps to node: {responsible_node}") # Add a new node with a custom weight hr.add_node('node4', {'weight': 10}) # Remove a node hr.remove_node('node2') # Get the distribution of keys across nodes (after changes) # Note: This is an example, actual distribution varies with keys and hash function. # For a real application, you'd query 'get_node' for many keys to see the effect. print("Current node configuration:", hr.conf) print("Node distribution (example property, not a real-time key distribution):") # The 'distribution' property is a Counter of how many points each node occupies on the ring. print(hr.distribution)

Debug

Known issues

breakingSince 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]

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]

affects: >=1.0

deprecatedPython 2 support was dropped. `uhashring` versions 1.2 and newer do not support Python 2. [1]

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]

affects: >=1.2

gotchaWhen 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]

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]

affects: All versions

gotchaCustom node weights significantly influence key distribution. Incorrectly configured weights can lead to uneven load distribution or 'hotspots' on specific nodes. [1]

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]

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'uhashring'

The 'uhashring' package has not been installed in your current Python environment.

fix

pip install uhashring

AttributeError: module 'uhashring' has no attribute 'HashRing'

The 'HashRing' class is not directly available via the top-level 'uhashring' module; it must be explicitly imported from it.

fix

from uhashring import HashRing

TypeError: Node must be a string, bytes or dict

The `add_node` or `add_nodes` method was called with a node definition that is not a string, bytes, or a dictionary, which are the only accepted types.

fix

Ensure that nodes are passed as strings (e.g., `'my_node'`) or dictionaries (e.g., `{'instance': 'my_node_instance', 'host': '127.0.0.1'}`) to `add_node` or `add_nodes`.

Upgrade

Version history

2.5latest on PyPI · released Aug 3, 2026

Audit

Dependencies

No dependency data recorded yet.

Agent activity

41 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ultrabug/uhashring ↗

packagehttps://pypi.org/project/uhashring/ ↗