py-geth

Join the conversation on Discord Tests PyPI version Python versions

Python wrapper around running geth as a subprocess

System Dependency

This library requires the geth executable to be present.

If managing your own bundled version of geth, set the path to the binary using the GETH_BINARY environment variable.

Installation

python -m pip install py-geth

Quickstart

To run geth connected to the mainnet

>>> from geth import MainnetGethProcess
>>> geth = MainnetGethProcess()
>>> geth.start()

Or in dev mode for testing. These require you to give them a name.

>>> from geth import DevGethProcess
>>> geth = DevGethProcess('testing')
>>> geth.start()

By default the DevGethProcess sets up test chains in the default datadir used by geth. If you would like to change the location for these test chains, you can specify an alternative base_dir.

>>> geth = DevGethProcess('testing', '/tmp/some-other-base-dir/')
>>> geth.start()

Each instance has a few convenient properties.

>>> geth.data_dir
"~/.ethereum"
>>> geth.rpc_port
8545
>>> geth.ipc_path
"~/.ethereum/geth.ipc"
>>> geth.accounts
['0xd3cda913deb6f67967b99d67acdfa1712c293601']
>>> geth.is_alive
False
>>> geth.is_running
False
>>> geth.is_stopped
False
>>> geth.start()
>>> geth.is_alive
True  # indicates that the subprocess hasn't exited
>>> geth.is_running
True  # indicates that `start()` has been called (but `stop()` hasn't)
>>> geth.is_stopped
False
>>> geth.stop()
>>> geth.is_alive
False
>>> geth.is_running
False
>>> geth.is_stopped
True
>>> geth.version
"1.17.2-stable"

When testing it can be nice to see the logging output produced by the geth process. py-geth provides a mixin class that can be used to log the stdout and stderr output to a logfile.

>>> from geth import LoggingMixin, DevGethProcess
>>> class MyGeth(LoggingMixin, DevGethProcess):
...     pass
>>> geth = MyGeth()
>>> geth.start()

All logs will be written to logfiles in ./logs/ in the current directory.

The underlying geth process can take additional time to open the RPC or IPC connections. You can use the following interfaces to query whether these are ready.

>>> geth.wait_for_rpc(timeout=30)  # wait up to 30 seconds for the RPC connection to open
>>> geth.is_rpc_ready
True
>>> geth.wait_for_ipc(timeout=30)  # wait up to 30 seconds for the IPC socket to open
>>> geth.is_ipc_ready
True

Installing specific versions of geth

This feature is experimental, best-effort, and subject to breaking changes. It is a convenience for building tagged geth source archives and is not covered by integration testing. Historical tags may become incompatible with current Go toolchains. Prefer geth's official downloads or another supported installation method for normal use.

Versions of geth dating back to v1.14.0 can be installed using py-geth. See install.py for the current list of supported versions.

Installation can be done via the command line:

$ python -m geth.install v1.17.2

Or from python using the install_geth function.

>>> from geth import install_geth
>>> install_geth('v1.17.2')

The installed binary can be found in the $HOME/.py-geth directory, under your home directory. The v1.17.2 binary would be located at $HOME/.py-geth/geth-v1.17.2/bin/geth.

About DevGethProcess

The DevGethProcess will run geth in --dev mode and is designed to facilitate testing. In that regard, it is preconfigured as follows.

  • A single account is created, allocated 1 billion ether, and assigned as the coinbase.
  • All APIs are enabled on both rpc and ipc interfaces.
  • Networking is configured to not look for or connect to any peers.
  • A networkid is not set as one can no longer be set along with --dev.
  • Verbosity is set to 5 (DEBUG)
  • The RPC interface tries to bind to 8545 but will find an open port if this port is not available.
  • The DevP2P interface tries to bind to 30303 but will find an open port if this port is not available.

Development

Clone the repository:

$ git clone git@github.com:ApeWorX/py-geth.git

Next, run the following from the newly-created py-geth directory:

$ uv sync

Running the tests

You can run the tests with:

pytest tests

Developer Setup

If you would like to hack on py-geth, please check out the Snake Charmers Tactical Manual for information on how we do:

  • Testing
  • Pull Requests
  • Documentation

We use prek to maintain consistent code style. Once installed, it will run automatically with every commit. You can also run it manually with uv run prek run --all-files. If you need to make a commit that skips the prek checks, you can do so with git commit --no-verify.

Development Environment Setup

You can set up your dev environment with the dev dependency group, which is installed by default when you run uv sync.

git clone git@github.com:ApeWorX/py-geth.git
cd py-geth
uv sync
uv run prek install

Release setup

Releases are published from GitHub Releases. The release tag is the canonical version source, setuptools-scm derives the package version from that tag, and the release workflow publishes to PyPI through trusted publishing.

Adding Support For New Geth Versions

There is an automation script to facilitate adding support for new geth versions: update_geth.py

To add support for a geth version, run the following line from the py-geth directory, substituting the version for the one you wish to add support for. Note that the v in the versioning is optional.

$ python update_geth.py v1_16_0

To introduce support for more than one version, pass in the versions in increasing order, ending with the latest version.

$ python update_geth.py v1_16_1 v1_16_2 v1_16_3

Always review your changes before committing as something may cause this existing pattern to change at some point. It is best to compare the git difference with a previous commit that introduced support for a new geth version to make sure everything looks good.

Project links

Data verified by PyPI on Aug 22, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (7.0.1)

Owner

PyPI data
Data sourced directly from PyPI's database.

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for fselmo from gravatar.com fselmo Avatar for kclowes from gravatar.com kclowes

Credits

Author: The Ethereum Foundation

Maintainer: ApeWorX Collective

GitHub Statistics

Data verified by PyPI on Aug 22, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python <4, >=3.10

Tags

ethereum go-ethereum geth

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

py_geth-7.0.0.tar.gz (41.7 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

py_geth-7.0.0-py3-none-any.whl (28.5 kB view details)

Uploaded Python 3

File details

Details for the file py_geth-7.0.0.tar.gz.

File metadata

  • Download URL: py_geth-7.0.0.tar.gz
  • Upload date:
  • Size: 41.7 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for py_geth-7.0.0.tar.gz
Algorithm Hash digest
SHA256 f92410802a758fbb2a473698d72cfaed3943f3f4e2be0bfd6376f322a398bfb1
MD5 702e41ace42c97bd56901f4d20b9be3f
BLAKE2b-256 b259db39b5c2211164e1c17618023d61212f77652dc3aa82481cd53c884e0ff6

See more details on using hashes here.

Provenance

The following attestation bundles were made for py_geth-7.0.0.tar.gz:

Publisher: publish.yaml on ApeWorX/py-geth

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file py_geth-7.0.0-py3-none-any.whl.

File metadata

  • Download URL: py_geth-7.0.0-py3-none-any.whl
  • Upload date:
  • Size: 28.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for py_geth-7.0.0-py3-none-any.whl
Algorithm Hash digest
SHA256 68d9064af1dd47cece9c7adcb609f28708c54564bca1f76211a05a8a19253e50
MD5 3c3418bf62aebe8fa66880c31c7132f4
BLAKE2b-256 396d9daeda0f2de6a6e7be1c9b42ebb83133de0d4852b5115b378466d39d375c

See more details on using hashes here.

Provenance

The following attestation bundles were made for py_geth-7.0.0-py3-none-any.whl:

Publisher: publish.yaml on ApeWorX/py-geth

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

7.0.1

2 files

This release

7.0.0 This release

2 files

Pre-release

7.0.0b1

2 files

6.4.0

2 files

6.3.0

2 files

6.2.0

2 files

6.1.0

2 files

6.0.0

2 files

5.6.0

2 files

5.5.0

2 files

5.4.0

2 files

5.3.0

2 files

5.2.1

2 files

5.2.0

2 files

5.1.0

2 files

5.0.0

2 files

Pre-release

5.0.0b3

2 files

Pre-release

5.0.0b2

2 files

Pre-release

5.0.0b1

2 files

4.4.0

2 files

4.3.0

2 files

4.2.0

2 files

4.1.0

2 files

4.0.0

2 files

3.14.0

2 files

3.13.0

2 files

3.12.0

2 files

3.11.0

2 files

3.10.0

2 files

3.9.1

2 files

3.9.0

2 files

3.8.0

2 files

3.7.0

2 files

3.6.0

2 files

3.5.0

2 files

3.4.0

2 files

3.3.0

2 files

3.2.0

2 files

3.1.0

2 files

3.0.0

2 files

2.4.0

2 files

2.3.0

2 files

2.2.0

2 files

2.1.0

2 files

2.0.1

2 files

2.0.0

3 files

1.13.0

3 files

1.10.2

3 files

1.10.1

3 files

1.10.0

3 files

1.9.0

3 files

1.8.0

3 files

1.7.1

3 files

1.7.0

3 files

1.6.0

3 files

1.5.0

3 files

1.4.1

3 files

1.4.0

3 files

1.3.0

3 files

1.2.0

3 files

1.1.0

3 files

1.0.0

3 files

0.9.0

3 files

0.8.0

3 files

0.7.0

3 files

0.6.0

3 files

0.5.0

3 files

0.4.0

3 files

0.3.0

3 files

0.2.0

3 files

0.1.0

3 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page