Alethzero super easy install guide for OSX

StephanTualStephanTual London, EnglandMember, Moderator Posts: 1,282 mod

Updated 11 May 2015 - Olympic Edition


This tutorial describes how to build the C++ GUI Ethereum Implementation, 'AlethZero', on OSX Mavericks. You can find a list of updates at the bottom of this post.

Since August 2014, new PoC binaries are released regularly on This makes building from source a little less necessary than it used to if you just want to have a very brief look at Ethereum, and is a good thing. That said, because the C++ client feature set, Solidity and the API are expected to be in development even after the Ethereum Frontier release, you will definitely want to be building from source regardless, very often (maybe even everyday if you are a developer). The below guide should help you establish a simple workflow to do so.

For convenience, if you're worried about messing things up on your computer (a real possibility), you can always use a Parallels virtual machine installed from your recovery partition - they offer a 14 day trial.

If you're finding yourself having difficulties, please post your question in the C++ category:, or join us on IRC and ask directly.

Finally, for all documentation please refer to the wiki:


Most of the below is thanks to the amazing hard work by @caktux‌ (, who built a 'brew tap' (an automated set of install scripts so to speak).

Keep in mind it is important that you do not use sudo. Sudoing is not required in most cases (after all, you installed most of your OSX apps without requiring it) and could lead to path issues down the line.

Install Brew

First, install brew. Installing brew will also install the xcode tools that are needed.

ruby -e "$(curl -fsSL"

Now run brew doctor

brew doctor

Install the caktux formulae for Ethereum

brew tap ethereum/ethereum

Installing Cpp Ethereum

Important note: the following command installs all dependencies and the latest version of the development branch for ethereum C++. This step can take a long time, especially on a Macbook Air (read: one hour or more!). In particular, it is normal for this process to appear to be 'stuck' with a line of text starting with "/b2 --prefix=/usr/local/Cellar/boost". Good news: it will only take a long time once, to compile boost. Updates will be considerably faster.

brew install cpp-ethereum --devel --with-gui --successful
brew linkapps cpp-ethereum

That's it! You're all set.


If you develop heavily with Ethereum, one of your life existential questions will quickly become 'which version am I really on'. Sure, brew deployment is automated these days, but many a time I've been left wondering if I was running the 'right' git commit version of a devel release, in case the buildbot had temporarily gone on strike.

The easiest way is to do this is to check the git commit. When running brew reinstall you should see a message along the lines of:
==> Cloning
Updating /Library/Caches/Homebrew/cpp-ethereum--git
==> Checking out revision 9071de1133439bebb7f706b34c53a943cf448ae6
Armed with this information you can simply check the hash against your favorite git client. I use Sourcetree, so in this case, I'd click 'jump to -> commit', paste "9071de1133439bebb7f706b34c53a943cf448ae6" and voila, if all went well, the client will take me to the last commit of the branch i select (develop or master).

Those who really enjoy stats can have a look at the buildbot output itself, which for brew devel C++ is located at C++ develop brew.


To upgrade, simply:

brew update && brew upgrade
brew reinstall cpp-ethereum --devel --with-gui --successful
brew linkapps cpp-ethereum

If brew reinstall fails with a message stating "reference is not a tree", then execute rm -rf /Library/Caches/Homebrew/cpp-ethereum--git and try again.

If you have opted to create a shortcut to AlethZero in your OS X dock, you will have to remove and re-add it for the link to still be valid.


Downloading the chain and processing it can take hours. I often like to play with new releases and try things out, so a back up is a must. To back the chain up, you'll have to use Eth, AlethZero little CLI cousin:

eth -E ~/name_of_file

This will export the chain in a compact format.

eth -I ~/name_of_file

... will of course reimport the chain (after validating it). It's not the fastest thing but it's still better than relying on your network connection.


The readme for the homebrew tap by @caktux‌ should cover most issues:

a) I press 'Go' and nothing happens

Before anything else, keep an eye on the log window, look for error messages, but give it time! It take a good 5 minutes from the UPnP connection on my machine to start downloading blocks - and a couple of hours to catch up on the full chain.

If you're not seeing any peers after a few minutes, make sure UPnP is on on your router, and working. Check for UPnP related messages in the AlethZero log window.

If that doesn't help, the bootstrap node is sometimes down, it's expected on a testnet. The simplest way is to press 'Go' anyway (to start the network), then identify a node on that has plenty of peers (the Go bootnodes are good for this. Click "Network > Connect to Peer" and input the IP of the node and the correct port (30303), as such: xxx:xxx:xxx:xxx:30303.

b) It's 'not working'!

First, upgrade. You might think that that version you installed last night is good enough but it's likely a new one is already out, and very often, the version number will not change after a merge from a debug branch, only the commit hash. So before trying anything else, please go through the 'upgrade' procedure described just above, and try again.

If you're still experiencing issues, close the client, backup ~/Library/Application Support/Ethereum/keys.* and ~/Library/Application Support/Ethereum/web3. Note that if all your keys have their own password then you only need .web3. Now delete the ~/Library/Preferences/com.ethereum.alethzero.plist file (it contains your layout preferences), as well as the ~/Library/Application Support/Ethereum/ folder (which contains the chain database and your keys). Afterwards and in order to really wipe the plist file, you'll have to run killall -u $USER cfprefsd to clear the OSX cache. Reopen the client and try again.

Still no luck? Please raise an issue on and include as much information as possible (ideally a debug log from OSX, a copy of your log pane in AlethZero, your OS and version, your hardware, etc.). You can include files by using pastebin.

c) I can't see the same block number as the other peers

You're on the wrong chain. You need to upgrade, as the protocol number probably has changed. See 'Upgrading' above. If you're on a devel branch, it's likely you'll have to find yourself checking for updates every day - keep an eye on the IRC channel for announcements.

d) Brew is throwing errors during brew doctor or won't install a certain dependency

If you are an existing developer, it's likely you'll have brew already installed alongside a lot of the dependencies AlethZero uses. In particular, if you have made modifications to certain dependencies, or 'locked' a brewed application to a certain version number, this can cause issues.

In order to solve this, locate the formula that's causing problems in cd /usr/local/Library/Formula/, then execute git reset --hard followed by brew update. Note that this could very likely 'break' other apps on your system so tread carefully. In fact, we recommend you to use a VM in this particular case.


This is no longer supported by brew.


Go read the tutorial on how to create your first Dapp! Also, have a look at the wiki: (keep in mind the various APIs are changing a lot even between minor version updates, although the documented APIs on the wiki should be relatively up to date)

Update History:
05/09/2014 - Initial release
07/09/2014 - Update re: chain switching issue and layout preference location on the file system.
08/09/2014 - updated brew install with --devel --successful flag instead of --devel --stable
19/09/2014 - added better upgrade instructions
20/09/2014 - minor edits
21/09/2014 - added a bit more around upgrades
22/09/2014 - further updates
02/10/2014 - corrected brew url install following update
08/10/2014 - updated for POC7
19/10/2014 - added note on how to clear cache for plist file
20/10/2014 - added a little more info on how to solve common issues
10/05/2015 - updated for Olympic
11/05/2015 - minor update on configuration and obtaining peers
12/05/2015 - fixed reference to cpp-ethereum--git regarding 'not a tree' issue
13/05/2015 - fixed references to keys
14/05/2015 - added tips on backups
Post edited by StephanTual on


Sign In or Register to comment.