Quickstart / Installation


The instructions below were tested on Ubuntu 16.04 LTS. They should also work on other Linux distributions and on macOS. For other operating systems, we recommend using an Ubuntu virtual machine (VM).

The BigchainDB Python Driver depends on:

  1. Python 3.5+
  2. A recent Python 3 version of pip
  3. A recent Python 3 version of setuptools
  4. cryptography and cryptoconditions

If you’re missing one of those, then see “How to Install the Dependencies” below before proceeding.

Next, to install the latest stable BigchainDB Python Driver (bigchaindb_driver) use:

$ pip3 install bigchaindb_driver

If you want to install an Alpha, Beta or RC version of the Python Driver, use something like:

$ pip3 install bigchaindb_driver==0.5.0a4

The above command will install version 0.5.0a4 (Alpha 4). You can find a list of all versions in the release history page on PyPI.

Next: determine the BigchainDB Root URL of the BigchainDB node or cluster you want to connect to.

How to Install the Dependencies

Dependency 1: Python 3.5+

The BigchainDB Python Driver uses Python 3.5+. You can check your version of Python using:

$ python --version


$ python3 --version

An easy way to install a specific version of Python, and to switch between versions of Python, is to use virtualenv. Another option is conda.

Dependency 2: pip

You also need to get a recent, Python 3 version of pip, the Python package manager.

If you’re using virtualenv or conda, then each virtual environment should include an appropriate version of pip.

You can check your version of pip using:

$ pip --version


$ pip3 --version

pip was at version 9.0.0 as of November 2016. If you need to upgrade your version of pip, then see the pip documentation.

Dependency 3: setuptools

Once you have a recent Python 3 version of pip, you should be able to upgrade setuptools using:

$ pip install --upgrade setuptools


$ pip3 install --upgrade setuptools

Dependency 4: cryptography and cryptoconditions

BigchainDB(server and driver) also depends on cryptography and cryptoconditions.

On Ubuntu 14.04 and 16.04, this works:

$ sudo apt-get update

$ sudo apt-get install python3-dev libssl-dev libffi-dev

For other operating systems, please refer to the cryptography installation guide.

Installing the Driver

Now you can install the BigchainDB Python Driver (bigchaindb_driver) using:

$ pip install bigchaindb_driver


$ pip3 install bigchaindb_driver

Next: determine the BigchainDB Root URL of the BigchainDB node or cluster you want to connect to.

Advanced Installation Options

See the Advanced Installation Options page.

Installation Guide for Developers

Here’s how to set up bigchaindb-driver for local development.

  1. Fork the bigchaindb-driver repo on GitHub.

  2. Clone your fork locally and enter into the project:

    $ git clone [email protected]:your_name_here/bigchaindb-driver.git
    $ cd bigchaindb-driver/
  3. Create a branch for local development:

    $ git checkout -b name-of-your-bugfix-or-feature

    Now you can make your changes locally.

  4. When you’re done making changes, check that your changes pass flake8 and the tests. For the tests, you’ll need to start the MongoDB, Tendermint and BigchainDB servers:

    $ docker-compose up -d bigchaindb
  5. flake8 check:

    $ docker-compose run --rm bigchaindb-driver flake8 bigchaindb_driver tests
  6. To run the tests:

    $ docker-compose run --rm bigchaindb-driver pytest -v
  7. Commit your changes and push your branch to GitHub:

    $ git add .
    $ git commit -m "Your detailed description of your changes."
    $ git push origin name-of-your-bugfix-or-feature
We use pre-commit which should be triggered with every commit. Some hooks will change files but others will give errors that needs to be fixed. Every time a hook is failing you need to add the changed files again. The hooks we use can be found in the yaml config file.
  1. Submit a pull request through the GitHub website.