Skip to main content

A Python3 Kademlia overlay network implementation.

Project description

Little Bird Kademlia P2P DHT Network

A Python3 Kademlia overlay network implementation.

Build Status MIT license



From PyPi (Stable version)

$ mkdir tmp && cd tmp

$ pip3 install little-bird

From GitHub (Bleeding Edge/Development version)

$ git clone

$ python3 -m virtualenv venv

$ pip3 install -r requirements.txt


Copy the .env.dist to .env found on the directory root and edit it as you see fit.

$ cp .env.dist .env && nano .env


Kademlia is a pure P2P overlay network compromising also of a DHT (Distributed Hash Table).

The algorithm was proposed in the following paper:

Often compared with the likes of Pastry and Chord, it is used in many projects in the networking world including but not limited to BitTorrent, Ethereum, Gnutella, IPFS.

FAQ: Is this Kademlia implementation for you?

Is it anonymous?

No. Nodes use naked IP addresses to locate each other and share information within the network

Is the shared information encrypted?

No.Information is shared within the network without any encryption. However, adding an encryption mechanism is trivial.

This can be done by adding some logic to the send_message() logic and implementing a custom message received handler.

Does this implementation work on the public Internet?

Due to the complications of NAT punching, we decided to forego an implementation that could work on the Internet.

However, this remains in our future plans.

Is this also a database?

Yes. A distributed one with a very low failure rate. You can store and retrieve values at will.

Why does it have a low failure rate?

Keys are automatically replicated within different nodes in the network. Nodes that have a longer uptime are also favoured in this setup.

In fact the probability of failure is lower than the probability of a node leaving the network. The event of a node leaving the network does not affect the database in anyway.

Is there a central tracker server, like a master coordinator?

No. Every node shares the same weight in the network.

Each node holds substantial information which is useful in node and key lookups.

Configuration information also spreads automatically as a side effect of key lookups.

Despite the lack of a tracker, all tracker functions are covered by Kademlia.

Feature Central Tracker Network DHT Based Network
Node Lookups [x] [x]
Key Lookups [x] [x]
Performance Increases With Load [ ] [x]
Susceptible to DDOS attacks [x] [ ]
Low failure rate [ ] [x]

Why do you keep on insisting that Kademlia is much more performant? Are you trying to sell it to me?

Because an increase in the number of nodes increases the performance of the network. Lookups are much faster.

Whereas in the case of a centralised network, a tracker might be overwhelmed, taking down the whole network with it.

But wont the higher number of nodes effectively DDOS the network?

No. Kademlia favours older nodes over newer nodes.

A DDOS attack would just put the attacking nodes on the networks waiting list chuckles villanously


python -m unittest

Behind the Scenes

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

little-bird-0.0.2.tar.gz (8.4 kB view hashes)

Uploaded source

Built Distribution

little_bird-0.0.2-py3-none-any.whl (10.2 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page