Redis Cluster lib in Python
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

Redis cluster CLI tools and libraries in Python. It supports Python 2.7 and 3.5 or higher. It supports Redis 3.x and 4.x cluster mode.


pip install redis-trib
easy_install redis-trib


NOTE: The following console commands or APIs do not support simultaneous operations on one cluster.

Console Commands

Cluster Manipulation

Create a cluster in some redis nodes (the nodes are cluster enabled, and none of them in any cluster) create NODE_HOST_a:PORT_a NODE_HOST_b:PORT_b ...

Add another node to a cluster, but neither set as slave nor migrating slots to it add_node --existing-addr CLUSTER_HOST:PORT --new-addr NEW_NODE_HOST:PORT

Add a slave node to a master (slave should not in any cluster) replicate --master-addr MASTER_HOST:PORT --slave-addr SLAVE_HOST:PORT

Remove a node from its cluster del_node --addr NODE_HOST:PORT

Shutdown an empty cluster (there is only one node left and no keys in the node) shutdown --addr NODE_HOST:PORT

Fix migrating slots in a node fix --addr HOST_HOST:PORT

Migrate slots (require source node holding all the migrating slots, and the two nodes are in the same cluster) migrate --src-addr SRC_HOST:PORT --dst-addr DST_HOST:PORT SLOT SLOT_BEGIN-SLOT_END

Rescue a failed cluster, specify host, port of one node in the cluster, and a free node rescue --existing-addr CLUSTER_NODE_HOST:PORT --new-addr NEW_NODE_HOST:PORT

List Cluster Nodes

List nodes in a cluster and output simple master slave relationship between them list --addr HOST:PORT


Total 4 nodes, 2 masters, 0 fail
M master 0
M master 8000
 S myself,slave
 S slave
M master 8384
 S slave

Each line represent one Redis node and a leading M means it is a master, while a leading S means slave. The second column contains address, the third contains its flags, the last column contains the number of slots assigned to it if it is a master, or its master's address if it is a slave.

Lines are sorted by the master addresses, and each slave will be displayed after its master.

The format may be changed in the future. If you need a stable API, use Redis CLUSTER NODES command instead. Or use the redistrib.command.list_nodes Python API, which is mentioned below.

Execute Command

Execute a command on each cluster node execute --addr HOST:PORT COMMAND ARGS... execute --addr HOST:PORT --master-only COMMAND ARGS... execute --addr HOST:PORT --slave-only COMMAND ARGS...

For example: execute --addr PING


More Examples

Please read the wiki.

Python APIs

Cluster Operation APIs

import redistrib.command

# start cluster on multiple nodes, all the slots will be shared among them
# the first argument is a list of (HOST, PORT) tuples
# for example, the following call will start a cluster on and
# this API will run the "cluster addslots" command on the Redis server;
#   you can limit the number of slots added to the Redis in each command by the `max_slots` argument
redistrib.command.create([('', 7000), ('', 7001)], max_slots=16384)

# add node to the cluster as a master
redistrib.command.add_node('', 7000, '', 7001)

# add node to the cluster as a slave to
redistrib.command.replicate('', 7000, '', 7002)

# remove node from the cluster
redistrib.command.del_node('', 7000)

# shut down the cluster
redistrib.command.shutdown_cluster('', 7001)

# fix a migrating slot in a node
redistrib.command.fix_migrating('', 7001)

# migrate slots; require source node holding the slots

# migrate slots #1, #2, #3 from to
redistrib.command.migrate_slots('', 7001, '', 7002, [1, 2, 3])

# rescue a failed cluster
# is one of the nodes that is still alive in the cluster
# and is the node that would take care of all failed slots
redistrib.command.rescue_cluster('', 7000, '', 8000)

Cluster Status APIs

import redistrib.command

# list all cluster nodes (attributes of which shown in the next section)
# args
#   - host: host of specified node
#   - port: port of specified node
#   - default_host: default host string if the specified node doesn't know its host
#   - filter_func: filter function that takes one ClusterNode parameter
#                  and returns False if the node should be excluded from the result
# returns
#   - nodes: all cluster nodes
#   - myself: the specified node itself, also contained by nodes
nodes, myself = redistrib.command.list_nodes('', 7000, default_host='',
                                             filter_func=lambda node: True)

# list all master nodes
# args same as list_nodes
# returns
#   - nodes: all master nodes
#   - myself: the specified node itself, contained by nodes if it's a master; won't be None even if it's a slave
nodes, myself = redistrib.command.list_masters('', 7000, default_host='')


redistrib.clusternode.ClusterNode: cluster node, attributes:

  • node_id: node id
  • host: known host, this value could be empty string if the node is newly launched
  • port: listening port
  • master: if the node is a master
  • slave: if the node is a slave
  • role_in_cluster: "master" or "slave"
  • fail: if the node is marked as "fail" or "fail?"
  • master_id: master's node_id if it's a slave, or None otherwise
  • assigned_slots: a list of assigned slots if it's a master; it won't contain slots being migrated
  • slots_migrating: boolean value for whether there are any slot(s) migrating or importing on this node