Welcom to Populus! Populus has (almost) everything you need for Ethereum blockchain development.

System Dependencies

Populus depends on the following system dependencies.

  • The Solidity Compiler : Contracts are authored in the Solidity language, and then compiled to the bytecode of the Ethereum Virtual Machine (EVM).
  • Geth: The official Go implementation of the Ethereum protocol. The Geth client runs a blockchain node, lets you interact with the blockchain, and also runs and deploys to the test blockchains during development.

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

Install Populus

Populus can be installed using pip as follows.

$ pip install populus

If you are installing on Ubuntu, and working with python3 (recommended):

$ pip3 install populus


With Ubuntu, use Ubuntu’s pip:

$sudo apt-get install python-pip

or, for python 3:

$sudo apt-get install python3-pip

You may need to install populus with sudo: $ sudo -H pip install populus

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

$ python setup.py install

Verify your installation

$ populus

Usage: populus [OPTIONS] COMMAND [ARGS]...


  -p, --project PATH  Specify a populus project directory
  -l, --logging TEXT  Specify the logging level.  Allowed values are
                      DEBUG/INFO or their numeric equivalents 10/20
  -h, --help          Show this message and exit.

  chain    Manage and run ethereum blockchains.
  compile  Compile project contracts, storing their...
  config   Manage and run ethereum blockchains.
  deploy   Deploys the specified contracts to a chain.
  init     Generate project layout with an example...

Great. Let’s have the first populus project.

A Word of Caution

Populus is a development environment. It was designed to make things easy and fun for the Python Ethereum developer. We use test blockchains, demo accounts, simple passwords, everything that is required to help you focus on the code.

But once the code is ready for work and deployment with real Eth, you should be careful. As there is a clear difference between running your iOS app in the Xcode simulator to the real actions of the app on the iPhone, or to take another example, between running a website localy on vs. running it on a real server which is opened to the entire internet, there is a difference between blockchain development environment, and when you deploy and send real Eth.

The core issue, as a developer, is that once you unlock an account, there is a running process with access to your Eth. Any mistake or security breach can cause loosing this Eth. This is not an issue with test blockchains and test tokens, but with real Eth it is.

As a rule:

[1] When you unlock an account to use real Ether, the unlocked account balance should have only the minimum Ether required for gas and the money transfers you unlocked if for. Ethereum accounts are free, so it will cost you nothing to have a dedicated account for your development, where you will send only the Ether you need it for, from time to time.

[2] Never unlock a real Ether account on a remote node. You can use a remote node, but not for actions that require an unlocked account. When you unlock an account on a remote node, anybody with access to the node has access to your funds. In other words, the geth instance that unlocked your acount should run on your local protected machine.

[3] Geth allows you to provide a password file, which is handy (more on it later). The password file should be protected by permissions.

Luckily, there are simple and effective practices to keep your Eth safe. See Protecting yourself and your funds

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.

Alternatively, you can init a new project by a directory:

$ populus -p /path/to/my/project/ init

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.

$ nano contracts/Greeter.sol


Check your IDE for Solidity extention/package.

Here is the contract:

pragma solidity ^0.4.11;

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 a simple contract:

  • The contract keyword starts a contract definition
  • The contract has one public “state” variable, named greeting.
  • The contract constructor function, function Greeter(), which has the same name of the contract, initializes with a default greeting of the string 'Hello'.
  • The greet function is exposed, and returns whatever string is set as the greeting,
  • The setGreeting function is available, and 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

For compiling outside the project directory use:

$ populus -p /path/to/my/project/ compile

The build/contracts.json file contains a lot of information that the Solidity compiler produced. This is required to deploy and work with the contract. Some important info is the application binary interface (ABI) of the contract, which will allow to call it’s functions after it’s compiled, and the bytecode required to deploy the contract, and the bytecode that will run once the contract sits on the blockchain.

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.

Note that both test functions accept a chain argument. This “chain” is actually a py.test fixture , provided by the populus pytest plugin. The chain in the tests is a populus “chain” object that runs a temporary blockchain called “tester”. The tester chain is ephemeral. All blockchain state is reset at the beginning of each test run and is only stored in memory, so obviously not usable for long term runnig contracts, but great for testing.

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.

Finally, similarly to the tests deployment, test the same deployment from the command line:

$ populus deploy --chain tester --no-wait-for-sync
> Found 1 contract source files
- contracts/Greeter.sol
> Compiled 1 contracts
- contracts/Greeter.sol:Greeter
Please select the desired contract:

    0: Greeter

Type 0 at the prompt, and enter.

Beginning contract deployment.  Deploying 1 total contracts (1 Specified, 0 because of library dependencies).

Deploying Greeter
Deploy Transaction Sent: 0x84d23fa8c38a09a3b29c4689364f71343058879639a617763ce675a336033bbe
Waiting for confirmation...

Transaction Mined
Tx Hash      : 0x84d23fa8c38a09a3b29c4689364f71343058879639a617763ce675a336033bbe
Address      : 0xc305c901078781c232a2a521c2af7980f8385ee9
Gas Provided : 465729
Gas Used     : 365729

Verified contract bytecode @ 0xc305c901078781c232a2a521c2af7980f8385ee9
Deployment Successful.

Nice. Of course, since this is an ad-hoc “tester” chain, it quits immediately, and nothing is really saved. But the deployment works and should work on a permanent blockchain, like the mainnet or testnet.

Again, outside the project directory use:

$ populus -p /path/to/my/project/ deploy --chain tester --no-wait-for-sync

Setup for development and contribution

In order to configure the project locally and get the whole test suite passing, you’ll need to make sure you’re using the proper version of the solc compiler. Follow these steps to install all the dependencies:

Virtual environment

If you don’t already have it, go ahead and install virtualenv with pip install virtualenv. You can then create and activate your Populus environment with the following commands:

$ cd populus
$ virtualenv populus
$ source populus/bin/activate

This allows you to install the specific versions of the Populus dependencies without conflicting with global installations you may already have on your machine.

Install dependencies

Now, run the following commands to install all the dependencies specified in the project except for solc:

$ pip install -r requirements-dev.txt
$ pip install -r requirements-docs.txt
$ pip install -e .

Install Solidity

You’ll have to install solidity, recommended from release 0.4.11 or greater.

Installation scripts building it:

First, clone the repository and switch to the proper branch:

$ git clone --recursive https://github.com/ethereum/solidity.git
$ cd solidity
$ git checkout release_0.4.13

You can also download the tar or zip file at:


Use the tar.gz file to build from source, and make sure, after extracting the file, that the “deps” directory is not empty and actually contains the dependencies.

If you’re on a Mac, you may need to accept the Xcode license as well. Make sure you have the latest version installed, and if you run into errors, try the following:

$ sudo xcodebuild -license accept

If you’re on Windows, make sure you have Git, CMake, and Visual Studio 2015.

Now, install all the external dependencies. For Mac:

$ ./scripts/install_deps.sh

Or, for Windows:

$ scripts\install_deps.bat

Finally, go ahead and build Solidity. For Mac:

$ mkdir build
$ cd build
$ cmake .. && make

Or, for Windows:

$ mkdir build
$ cd build
$ cmake -G "Visual Studio 14 2015 Win64" ..

The following command will also work for Windows:

$ cmake --build . --config RelWithDebInfo


This should have installed everything you need, but let’s be sure. First, try running:

$ which solc

If you didn’t see any output, you’ll need to move the solc executable file into the directory specified in your PATH, or add an accurate PATH in your bash profile. If you can’t find the file, you may need to run:

$ npm install -g solc

This should install the executable wherever your Node packages live.

Once you see output from the which solc command (and you’re in the Populus directory with the virtualenv activated), you’re ready to run the tests.

$ py.test tests/

At this point, all your tests should pass. If they don’t, you’re probably missing a dependency somewhere. Just retrace your steps and you’ll figure it out.