System Dependencies

Populus depends on the following system dependencies.

  • Solidity : For contract compilation
  • Go Ethereum: For running test chains and contract deployment.

In addition, populus needs some system dependencies to be able to install the PyEthereum library.

Debian, Ubuntu, Mint

sudo apt-get install libssl-dev

Fedora, CentOS, RedHat

sudo yum install openssl-devel


brew install pkg-config libffi autoconf automake libtool openssl


Populus can be installed using pip as follows.

$ pip install populus

By default populus will use standard library tools for io operations like threading and subprocesses. Populus can be configured to instead use gevent. To install with gevent support:

$ pip install populus[gevent]

To enable gevent set the environment variable THREADING_BACKEND=gevent.

Installation from source can be done from the root of the project with the following command.

$ python setup.py install

Initializing a new project

Populus can initialize your project using the $ populus init command.

$ populus init
Wrote default populus configuration to `./populus.json`.
Created Directory: ./contracts
Created Example Contract: ./contracts/Greeter.sol
Created Directory: ./tests
Created Example Tests: ./tests/test_greeter.py

Your project will now have a ./contracts directory with a single Solidity source file in it named Greeter.sol, as well as a ./tests directory with a single test file named test_greeter.py.

Compiling your contracts

Before you compile our project, lets take a look at the Greeter contract that is generated as part of the project initialization.

pragma solidity ^0.4.0;

contract Greeter {
    string public greeting;

    function Greeter() {
        greeting = "Hello";

    function setGreeting(string _greeting) public {
        greeting = _greeting;

    function greet() constant returns (string) {
        return greeting;

Greeter is simple contract that is initialized with a default greeting of the string 'Hello'. It exposes the greet function which returns whatever string is set as the greeting, as well as a setGreeting function which allows the greeting to be changed.

You can now compile the contract using $ populus compile

$ populus compile
============ Compiling ==============
> Loading source files from: ./contracts

> Found 1 contract source files
- contracts/Greeter.sol

> Compiled 1 contracts
- Greeter

> Wrote compiled assets to: ./build/contracts.json

Testing your contract

Now that you have a basic contract you’ll want to test that it behaves as expected. The project should already have a test module named test_greeter.py located in the ./tests directory that looks like the following.

def test_greeter(chain):
    greeter, _ = chain.provider.get_or_deploy_contract('Greeter')

    greeting = greeter.call().greet()
    assert greeting == 'Hello'

def test_custom_greeting(chain):
    greeter, _ = chain.provider.get_or_deploy_contract('Greeter')

    set_txn_hash = greeter.transact().setGreeting('Guten Tag')

    greeting = greeter.call().greet()
    assert greeting == 'Guten Tag'

You should see two tests, one that tests the default greeting, and one that tests that we can set a custom greeting. You can run tests using the py.test command line utility which was installed when you installed populus.

$ py.test tests/
collected 2 items

tests/test_greeter.py::test_greeter PASSED
tests/test_greeter.py::test_custom_greeting PASSED

You should see something akin to the output above with three passing tests.