Ethereum Geth: Installing and Running a Node

Ethereum Geth: Installing and Running a Node

In order to participate in a blockchain, there usually is a need to run some form of client software that implements the features required to become a node. Even for actions such as simply sending a transaction to the network, a node is usually required. Participation in the Ethereum blockchain can be done by making use of Ethereum Geth, the command line interface for running a node on the Ethereum network, which has been implemented using the Go programming language.

The goal of Ethereum has always been to provide a number of different client software implementations, written in different programming languages, that will foster a diverse ecosystem within Ethereum. However, by far the most mature implementation of Ethereum is “Go Ethereum”, abbreviated to Geth. While there are other clients, notably Parity, Geth can be seen as the defacto reference implementation for running an Ethereum node.

In this article, we discuss Ethereum Geth, its architecture, and how it can be used to run an Ethereum node or light client.

Ethereum Geth Architecture

Ethereum GethThe above diagram illustrates the architecture of the Ethereum Geth client at a high level. At the lowest level, a peer-to-peer (P2P) protocol is in charge of communication on the network, and is also responsible for discovering peers on the network. The communication mechanisms used at this level is based on the Gossip algorithm. This classic distributed systems algorithm stems from the 1980s, and models network communication based on the way epidemics or rumors spread through the population. The idea is simple but powerful: nodes on the network relay messages to other nodes that they are directly connected to, these nodes can be regarded as being their neighbours. Eventually, every node should receive relayed messages as they spread throughout the entire network.

On top of the P2P mechanism, Ethereum Geth implements three main modules. Apart from the actual Ethereum client implementation, Geth also includes Swarm and Whisper. Swarm is a distributed file system, akin to the Interplanetary Filesystem (IPFS), which is aimed at storing large amounts of data cheaply and in a decentralized manner. Whisper is a decentralized messaging protocol that allows communication between endpoints without relying on blockchain transactions.

The actual Ethereum-specific module implements the Ethereum Virtual Machine for transaction processing. The blockchain state is stored in the LevelDB key-value database. In order for applications to connect to a running Geth instance, a JSON RPC API is exposed. This can be used to connect directly, or through a language-specific library, such as web3.js.


Installing Geth is relatively straightforward. Binary packages for Mac OS X, Windows and Linux can be found on the projects latest release download page. These packages include stand-alone pre-compiled binaries that can be run out of the box in most cases. It is also possible to use existing operating system package managers, such as Homebrew on Mac OS X:

  • brew tap ethereum/ethereum
  • brew install ethereum

Purists, or users of unusual binary platforms, may also build Ethereum Geth from source. This can even be used to install Geth on small devices, such as a Raspberry Pi (light-client only). To do so, a Go compiler is required. Installation of Go is platform dependent, but pre-built packages exist for all major operating systems.

Once Go is installed, it is a question of downloading the latest Geth source package from the release page or cloning the GitHub repository:

  • git clone

Geth can then be built by running the following command within the source code directory:

  • make geth

The resulting binary can be run from anywhere, but it is usually a good idea to move the executable into a common system directory within the operating system’s execution path, to ensure it can be run the same way as any other operating system binary.

Creating Accounts and Connecting to the Ethereum Blockchain

Once Geth is installed, it can be run by typing:

  • geth

However, there are a few things worth considering first. First of all, no Ethereum client can do much without an Ethereum account. Geth can import existing private keys or create new ones. A new key pair is created with the following command:

  • geth account new

The other important issue is the sync mode that should be used. Geth can only be used once it has synced up its state with the blockchain. This can take a long time, depending on how much state is supposed to be downloaded. There are three sync modes that can be set with the following command:

  • –syncmode “mode”

Options for sync mode are “fast”, “full” or “light”, with the software defaulting to “fast” when no sync mode is specified. “Full” downloads all block headers, block data, and validates all transactions. Choosing “fast” accelerates this by only verifying the most recent transaction history on the Ethereum blockchain. Finally, “light” downloads the current state, but does not do any verification. A light node will rely on its peers to process and verify transactions that are initiated on the blockchain.

Running Ethereum Geth

Once Geth is running, one can interact with it through the JSON RPC interface. An easy way to do this is to use the Geth executable itself to connect to a running instance:

  • geth attach

This opens up a JavaScript console that allows for web3.js commands. For example, to check whether the running instance has already synced up to the Ethereum network, the following command can be used:

  • > web3.eth.syncing

A list of accounts can be seen with the following command:

  • > eth.accounts

Of course, Geth can also be interacted with from other programming languages that support bindings for the JSON RPC API, or you can send JSON-formatted commands to the API directly. Geth exposes the API on port 8545, but it may have to be enabled at start-up by adding the following command line option:

  • geth –rpc

In fact, Geth supports a number of useful command line options to change the default behavior, such as the network it connects to. A full list of options can be found in the official documentation.