Python-etcd documentation

An asynchronous python client for Etcd



Install etcd

From source

$ python install


Create a client object

import aio_etcd as 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

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

You can also atomically update a result:

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

Get a key

#recursively read a directory
r = await'/nodes', recursive=True, sorted=True)
for child in r.children:
    print("%s: %s" % (child.key,child.value))

await'/nodes/n2', wait=True) #Waits for a change in value in the key before returning.
await'/nodes/n2', wait=True, waitIndex=10)

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

Delete a key

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

Locking module

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

# Use the lock object:
await 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
await lock.acquire(lock_ttl=60)  # renew a lock
await lock.release()  # release an existing lock
lock.is_acquired  # False

# The lock object may also be used as a context manager:
# (Python 3.5+)
client = etcd.Client()
async with etcd.Lock(client, 'customer1') as my_lock:
    my_lock.is_acquired  # True
    await my_lock.acquire(lock_ttl=60)
my_lock.is_acquired  # False

Get machines in the cluster

machines = await client.machines()

Get leader of the cluster

leader_info = await client.leader()

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