Getting Started

aohb edited this page Dec 9, 2016 · 4 revisions

Getting Started with pyethapp

This guide helps you getting the Ethereum Python client up and running. It is intended for users of UNIX-like operating systems. Unfortunately, Windows users are on their own for now. (If you are using Windows 10 64bit consider using Ubuntu on Windows - which is basically a Ubuntu user space and bash shell, which runs natively in a Windows 10 cmd.exe console. More Info)

There are two sources where you can install pyethapp from: the Python Package Index (PyPI) and GitHub. The version on PyPI is not regularly updated and severeley outdated at the moment. Therefore, we highly recommend installing from GitHub for the time being.

In both cases, pyethapp will be installed in a virtual environment. While not required, this avoids potential interference with other Python programs and their dependencies.


  • Python 2.7 (2.6 should work as well, 2.5 doesn't work, 3.x might work at some point in the future)
  • Pip (included in Python versions 2.7.9 and greater)
  • Git (only for installation from GitHub)
  • Virtualenv

Installing from Github

First, go to the directory where you want to install pyethapp, and clone its repository:

~$ cd ethereum
~/ethereum$ git clone

Then, cd into the automatically created directory and set up a virtual environment there. Activate it and make sure this was successful (your command line prompt should have changed):

~/ethereum$ cd pyethapp
~/ethereum/pyethapp$ virtualenv .venv
~/ethereum/pyethapp$ source .venv/bin/activate
(.venv) ~/ethereum/pyethapp/$ # note the "(.venv)"

Finally, install the client from the downloaded source in the virtual environment (this may take some time):

(.venv) ~/ethereum/pyethapp/$ pip install --editable .

Now you should be able to run pyethapp. To test this, invoke it without arguments:

(.venv) ~/ethereum/pyethapp/$ pyethapp
Usage: pyethapp [OPTIONS] COMMAND [ARGS]...

  Welcome to ethapp version:pyethapp/v0.9.18/linux2/py2.7.9


Installing from PyPI

Begin with setting up a virtual environment named pyethapp. In contrast to the installation procedure above, there's no need to create a distinct parent directory, as it would be empty apart from the environment anyway.

~$ cd ethereum
~/ethereum$ virtualenv pyethapp

Next, activate the virtualenv:

~/ethereum$ source pyethapp/bin/activate
(pyethapp) ~/ethereum/pyethapp$  # note the "(pyethapp)"

Your command line prompt should have changed, indicating that you are now operating from inside the virtual environment called “pyethapp”. Being assured of that, install the pyethapp package from PyPI:

(pyethapp) ~/ethereum$ pip install pyethapp

If the installation was successful, pyethapp can now be executed:

(pyethapp) ~/ethereum/$ pyethapp
Usage: pyethapp [OPTIONS] COMMAND [ARGS]...

  Welcome to ethapp version:pyethapp/v0.9.18/linux2/py2.7.9


Starting pyethapp from outside of the virtual environment

Regardless of whether you installed from PyPI or GitHub, as soon as you've left the virtual environment, your shell won't know where to find the command pyethapp anymore (it's hidden in the bin folder of the environment). It's still possible to run it, but you have to specify its full path (<path to virtual environment>/bin/pyethapp). To avoid that, you can symlink the executable to a directory in your system path:

(.venv) ~/ethereum/pyethapp$ deactivate  # leaving virtualenv
~/ethereum/pyethapp$ pyethapp
pyethapp: command not found
~/ethereum/pyethapp$ ln -s .venv/bin/pyethapp ~/bin/pyethapp
~/ethereum/pyethapp$ cd ../..
~$ pyethapp
Usage: pyethapp [OPTIONS] COMMAND [ARGS]...

  Welcome to ethapp version:pyethapp/v0.9.18/linux2/py2.7.9


What's next?

If everything went right, you should now be able to start a node:

$ pyethapp run

pyethapp will connect to the network and start syncing the blockchain. Congratulations!

Head back to the wiki home page for more in-depth help topics.