uhashring

What it is and what it does

uhashring is a pure-Python library that implements consistent hashing, a technique for distributing keys across a set of nodes in a way that minimizes remapping when nodes join or leave the system. It's commonly used in distributed caches, databases, and load-balancing scenarios where you need stable key-to-node assignments. The library offers both a simple API for basic use and advanced configuration options including custom hash functions, per-node weights, and ketama compatibility for interoperability with other systems.

The package supports multiple hash strategies: by default it uses MD5 with 160 virtual nodes per node, but can also operate in ketama-compatible mode for systems that need it. You can customize the hash function, weight calculation, and virtual node count per node. It has no external runtime dependencies and runs on CPython and PyPy, making it suitable for a range of deployment scenarios.

Use it for:

• Distributing cache keys across multiple memcached or Redis instances while maintaining stable mappings during server additions or failures.
• Load-balancing requests or data across a cluster of backend nodes with minimal key remapping during scaling events.
• Implementing sharding logic in a distributed database where keys must consistently map to the same shard.
• Migrating from libketama-based systems while maintaining hash ring compatibility and key distribution.
• Building a custom distributed system where you need fine control over node weights and virtual node counts.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

uhashring implements consistent hashing in pure Python, mapping keys to nodes in a distributed system while minimizing reshuffling when nodes are added or removed.

Yes. uhashring is a mature, actively maintained library with no security vulnerabilities, zero runtime dependencies, and broad Python version support. It solves a well-defined problem (consistent hashing) with a clean API and optional advanced features. Install it if you need stable key-to-node mapping in a distributed system or cache layer.

Install

uhashring on PyPI

pip install uhashring

uv add uhashring

poetry add uhashring

Installing uhashring

Before you install

Low install friction; pure Python with no runtime dependencies. Actively maintained as of 2026-08-05, supporting current Python versions (3.10+) with PyPy compatibility.

License in practice

BSD-3-Clause permissive license allows use in commercial and proprietary projects with minimal restrictions.

Quickstart

from uhashring import HashRing

# Create a consistent hash ring with 3 nodes
hr = HashRing(nodes=['node1', 'node2', 'node3'])

# Get the target node for a key
target_node = hr.get_node('coconut')

Requires Python 3.10 or later.

Verify before relying

• Performance characteristics (lookup time, ring regeneration speed) under various node counts and topologies.
• Actual collision rates and distribution uniformity compared to ketama or other hash functions in production scenarios.

Package facts

Evidence: uhashring-2.5-py3-none-any.whl

Tags

More Python Modules packages