Registry / database / tooz
library8.1.0pypypi✓ verified 84d ago

Tooz is a Python library designed to provide distributed systems primitives such as group membership, leader election, distributed locking, and distributed messaging. It offers a unified API over various backend drivers like Redis, ZooKeeper, and Etcd. Currently at version 8.1.0, it is actively maintained as part of the OpenStack ecosystem with regular updates.

pip install tooz
INSTALL
IMPORT
SIG · TOOZ
T
tooz
databasepythonv8.1.0
Install
4.2s avg
Import
Disk
48MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v8.1.0 · 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.103.930 runs
installs and imports cleanly · install 0.0s · import 0.000s · 44.1MB
glibc
py 3.103.930 runs
installs and imports cleanly · install 4.2s · import 0.000s · 46MB
48MB installed
● package 48MB
Code
Verified usage

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

ToozError
from tooz import ToozError
from tooz.drivers import DriverFactory
NotImplemented
from tooz import NotImplemented
from tooz.drivers import DriverFactory

This quickstart demonstrates how to initialize a `tooz` driver using `DriverFactory` and acquire a distributed lock. It uses a file-based driver by default for easy local testing, but can be configured with a `TOOZ_BACKEND` environment variable for real backends like Redis or Zookeeper. The example shows how to acquire a lock with a timeout and ensures proper cleanup.

import os import time from tooz.drivers import DriverFactory # Use a file-based driver for local testing or set an environment variable for a real backend # e.g., export TOOZ_BACKEND="redis://localhost:6379/0" (for Redis DB 0) # e.g., export TOOZ_BACKEND="zookeeper://localhost:2181" connection_string = os.environ.get("TOOZ_BACKEND", "file:///tmp/tooz_locks_example") # Group ID for coordination primitives, must be bytes group_id = b"my_application_group" driver = None try: # Initialize the driver factory. This will select the appropriate driver # based on the connection string prefix (e.g., 'redis://', 'file://'). driver = DriverFactory(connection_string, group_id) print(f"Connected to tooz backend: {connection_string}") # Example: Acquire a distributed lock lock_name = b"my_critical_section" # `timeout` specifies how long to wait to acquire the lock. # `heartbeat_timeout` specifies how often to renew the lock if acquired. lock = driver.get_lock(lock_name, timeout=5, heartbeat_timeout=1) print(f"Attempting to acquire lock '{lock_name.decode()}'...") if lock.acquire(): print("Lock acquired successfully! Performing critical work...") # Simulate some work time.sleep(2) print("Work done, releasing lock.") # Lock is automatically released by the 'finally' block when driver disconnects # or can be explicitly released with lock.release() else: print("Could not acquire lock within timeout.") finally: if driver: # Ensure the driver is disconnected to release resources and locks. driver.disconnect() print("Disconnected from tooz backend.")
Debug
Known issues
breakingTooz versions 8.0.0 and above require Python 3.10 or newer. Older Python versions are no longer supported.
fix
Upgrade your Python environment to 3.10 or later, or use an older `tooz` version (e.g., `tooz<8`) if you must stay on Python 3.9 or earlier.
affects: >=8.0.0
gotchaTooz drivers for specific backends (e.g., Redis, Zookeeper) are optional dependencies and must be installed separately using 'extras'. Installing just `pip install tooz` will only provide the core library and file/memory drivers.
fix
Install `tooz` with the desired backend extra, for example: `pip install tooz[redis]`, `pip install tooz[zookeeper]`, or `pip install tooz[etcd3]`.
affects: all
deprecatedWhile `tooz.coordination.CoordinationDriver` is still available, `tooz.drivers.DriverFactory` is the recommended and more robust entry point for initializing drivers since `tooz` v7.0.0. Direct instantiation of specific drivers (e.g., `tooz.drivers.redis.RedisDriver`) is also less portable.
fix
Use `from tooz.drivers import DriverFactory` and initialize your driver with `driver = DriverFactory(connection_string, group_id)`.
affects: >=7.0.0
gotchaDistributed locks obtained via `tooz` are not automatically released if the process crashes or loses connectivity without properly calling `driver.disconnect()` or `lock.release()`. Use `try...finally` blocks to ensure cleanup.
fix
Always wrap your `tooz` driver usage, especially lock acquisition, in `try...finally` blocks to ensure `driver.disconnect()` is called. Consider using `with driver.get_lock(...) as lock:` if supported for the specific primitive and driver.
affects: all
Upgrade
Version history
8.1.0latest on PyPI · released Feb 19, 2026
Audit
Dependencies
redisoptionalRequired for the Redis driver. Install with 'pip install tooz[redis]'.
kazoooptionalRequired for the Zookeeper driver. Install with 'pip install tooz[zookeeper]'.
python-etcd3optionalRequired for the Etcd driver. Install with 'pip install tooz[etcd3]'.
Agent activity
46 hits · last 30 days
node
40
OpenAI (training)
2
Resources
tooz — pip install tooz · libregistry