---
id: uhashring
version: "2.5"
license: BSD-3-Clause
license_treatment: permissive
maintenance: active
---

# uhashring — Full featured consistent hashing python library compatible with ketama.

License: permissive · Maintenance: active · Downloads: 593.1K/mo

## 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 above — 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

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

- License: BSD-3-Clause (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 593.1K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

consistent hashing python, distributed cache key mapping, ketama compatible hashing, hash ring implementation, node distribution algorithm, memcache consistent hash, virtual nodes hashing, distributed-systems, caching, hashing

[View on SkillFed](https://skillfed.io/packages/uhashring) · [View on PyPI](https://pypi.org/project/uhashring/)