py-geth

6.4.0 verified Fri May 01 auth: no python

py-geth is a Python library for running Go-Ethereum (geth) as a subprocess. It provides a convenient interface to manage Ethereum nodes, including downloading, installing, and interacting with geth. The current version is 6.4.0, supporting Python 3.8+. The library is actively maintained and follows the Ethereum release cadence.

pip install py-geth

Common errors

error FileNotFoundError: [Errno 2] No such file or directory: 'geth' ↓

cause geth binary is not installed or not in PATH.

fix

Install geth using install_geth() or provide an explicit path with geth_executable.

error geth: command not found ↓

cause geth binary is not installed in the system PATH.

fix

Use from geth import install_geth; install_geth('1.13.4') to download the binary.

error AttributeError: 'GethProcess' object has no attribute 'rpc_url' ↓

cause The property `rpc_url` was added in v5. Older versions use `http_port`.

fix

Access geth.http_port instead, or upgrade to py-geth >=5.

Warnings

breaking In v4+, the package uses an explicit binary download step. Previously, GethProcess would automatically download geth. Now you must call `install_geth()` or provide a pre-installed binary. ↓

fix Use `from geth import install_geth; install_geth()` before starting a process.

gotcha On macOS, geth binaries are not signed, and macOS Gatekeeper may block execution. This causes process.start() to fail silently. ↓

fix Manually download and sign the binary, or run `xattr -dr com.apple.quarantine /path/to/geth`.

deprecated The `GethProcess` constructor argument `python_executable` is deprecated in v5+. Use `geth_executable` to specify the path to the geth binary. ↓

fix Replace `python_executable='/path/to/geth'` with `geth_executable='/path/to/geth'`.

gotcha The default data directory is relative to the current working directory, which can cause unexpected behavior if not using absolute paths. ↓

fix Always provide an absolute path for the data directory, e.g., `DevGethProcess('/absolute/path')`.

Imports

GethProcess
```
from geth import GethProcess
```
The main class to manage a geth node instance.
get_binary_path
```
from geth import get_binary_path
```
Utility to get the path to the geth binary.
install_geth
```
from geth import install_geth
```
Function to install a specific version of geth.
DevGethProcess
```
from geth import DevGethProcess
```
A subclass that automatically uses --dev mode.

Quickstart

Starts a Geth node in developer mode with a pre-funded account and mining enabled.

from geth import DevGethProcess

# Start a dev geth instance with default settings
geth = DevGethProcess('~/ethereum')
geth.start()
# Wait until the node is ready
geth.wait_for_rpc(timeout=60)
print(f'RPC available at {geth.rpc_url}')
geth.stop()