Python-etcd documentation

A python client for Etcd



Install etcd

From source

$ python install


Create a client object

import etcd

client = etcd.Client() # this will create a client against etcd server running on localhost on port 4001
client = etcd.Client(port=4002)
client = etcd.Client(host='', port=4003)
client = etcd.Client(host='', port=4003, allow_redirect=False) # wont let you run sensitive commands on non-leader machines, default is true
client = etcd.Client(

Set a key

client.write('/nodes/n1', 1)
# with ttl
client.write('/nodes/n2', 2, ttl=4)  # sets the ttl to 4 seconds
# create only
client.write('/nodes/n3', 'test', prevExist=False)
# Compare and swap values atomically
client.write('/nodes/n3', 'test2', prevValue='test1') #this fails to write
client.write('/nodes/n3', 'test2', prevIndex=10) #this fails to write
# mkdir
client.write('/nodes/queue', None, dir=True)
# Append a value to a queue dir
client.write('/nodes/queue', 'test', append=True) #will write i.e. /nodes/queue/11
client.write('/nodes/queue', 'test2', append=True) #will write i.e. /nodes/queue/12

You can also atomically update a result:

result ='/foo')
print(result.value) # bar
result.value += u'bar'
updated = client.update(result) # if any other client wrote '/foo' in the meantime this will fail
print(updated.value) # barbar

Get a key'/nodes/n2').value
#recursively read a directory
r ='/nodes', recursive=True, sorted=True)
for child in r.children:
    print("%s: %s" % (child.key,child.value))'/nodes/n2', wait=True) #Waits for a change in value in the key before returning.'/nodes/n2', wait=True, waitIndex=10)

# raises etcd.EtcdKeyNotFound when key not found
except etcd.EtcdKeyNotFound:
    # do something
    print "error"

Delete a key

client.delete('/nodes', dir=True) #spits an error if dir is not empty
client.delete('/nodes', recursive=True) #this works recursively

Locking module

# Initialize the lock object:
# NOTE: this does not acquire a lock yet
client = etcd.Client()
lock = etcd.Lock(client, 'my_lock_name')

# Use the lock object:
lock.acquire(blocking=True, # will block until the lock is acquired
      lock_ttl=None)  # lock will live until we release it
lock.is_acquired  # True
lock.acquire(lock_ttl=60)  # renew a lock
lock.release()  # release an existing lock
lock.is_acquired  # False

# The lock object may also be used as a context manager:
client = etcd.Client()
with etcd.Lock(client, 'customer1') as my_lock:
    my_lock.is_acquired  # True
my_lock.is_acquired  # False

Get machines in the cluster


Get leader of the cluster


Development setup

To create a buildout,

$ python
$ bin/buildout

to test you should have etcd available in your system path:

$ bin/test

to generate documentation,

$ cd docs
$ make

Release HOWTO

To make a release,

  1. Update release date/version in NEWS.txt and
  2. Run ‘python sdist’
  3. Test the generated source distribution in dist/
  4. Upload to PyPI: ‘python sdist register upload’
  5. Increase version in (for next release)

List of contributors at

Code documentation