web3.py, the Python way to talk to Ethereum

Where web3.js goes JavaScript, web3.py goes Python

web3.py is a Python interface to the Ethereum blockchain and its ecosystem, for building decentralized applications and interacting with smart contracts. The same job exists in JavaScript, where web3.js is the long-established counterpart, and the split between the two libraries is mostly a split of language: pages and Node services on one side, Python scripts, notebooks and test suites on the other. Choosing web3.py means your Ethereum calls sit next to your data analysis and your CI in one runtime, instead of bridging out to a separate Node process. The library is published on PyPI as web3, requires Python >=3.10,<4, and its classifiers cover versions 3.10 through 3.14.

python -m pip install web3 and the tree it drags in

Installation is a single command:

python -m pip install web3

Behind it sits an Ethereum-specific core: eth-abi>=6 for ABI encoding, eth-account>=0.14 for accounts and signing, eth-utils>=5.3.0 and eth-typing>=5.0.0 for shared primitives, hexbytes>=2 for byte handling, and eth-hash[pycryptodome]>=0.5.1 selecting a hashing backend. Transport comes from three clients, requests>=2.23.0 for synchronous HTTP, aiohttp>=3.7.4.post0 for the async path, and websockets>=14 for socket connections. pydantic>=2.4 appears for typed models. Two dependencies are conditional: pywin32>=223 arrives only where platform_system == 'Windows', and typing-extensions>=4.0.1 only below Python 3.11. Reading the list before installing tells you what the library leans on and which of it you already run.

v8.0.0, a version derived from git, and the 3.10 floor

Release v8.0.0 was tagged on 2026-08-31, and the last push to the repository was on 2026-09-29. The installed version is not hardcoded in pyproject.toml: the file declares dynamic = ['version'] and its build requirements include setuptools_scm[toml]>=8, so the published number derives from repository state at build time. requires-python is set to >=3.10,<4, with classifiers listing 3.10, 3.11, 3.12, 3.13 and 3.14, and Development Status sits at 5, Production/Stable. For a team planning an upgrade, 8.0.0 is a major-version boundary: the release notes published in the documentation are the place to check what moved across it.

ens/: name resolution ships inside the project

Around the main web3/ package the repository carries a sibling directory, ens/. Ethereum Name Service support, the mapping of human-readable names to blockchain addresses, is part of this project rather than a third-party add-on, and the Dockerfile copies ens/ alongside web3/ when it builds its image. That layout matters for packaging expectations: code imported through ens comes from the same repository, the same version tag and the same issue tracker as the rest of the library. The tree is completed by docs/, a tests/ directory with its conftest.py, and a .readthedocs.yaml that publishes web3py.readthedocs.io.

The Dockerfile builds a python:3.13 sandbox, not a service

For containerized work the repository ships a Dockerfile and a docker-compose.yml. The image starts FROM python:3.13, installs libssl-dev through apt-get, copies in web3/, tests/, ens/, pyproject.toml and README.md, then syncs dependencies with uv:

FROM python:3.13
RUN apt-get update && apt-get install -y libssl-dev
RUN pip install uv \
  && UV_CACHE_DIR=/tmp/uv-cache uv sync --all-extras --all-groups

docker-compose.yml defines a single service named sandbox, mounts the repository at /code as a volume, and runs tail -f /dev/null, a command that does nothing but keep the container alive. That is an interactive sandbox shape rather than a service shape: no port is exposed, and the expectation is that you exec in and run commands against the mounted code.

eth-tester, the beta-pinned extra behind node-free tests

One optional dependency group stands out. Installing the tester extra brings in eth-tester[py-evm], pinned to a pre-release band:

[project.optional-dependencies]
tester = [
    "eth-tester[py-evm]>=0.14.0b1,<0.15.0b1",
]

The py-evm inside the extra is a Python implementation of the Ethereum Virtual Machine, so the extra exists to run tests against a chain that lives in-process instead of a node reached over the network. The pin itself carries information: a beta version range means the testing stack moves underneath you, and lockfiles that ignore the extra cannot opt into it later for free. The README does not document the extra. pyproject.toml is the source of truth for it.

A short README that points instead of explaining

The README is short: a scope sentence, the Python 3.10+ note, one install command and a set of pointers. Those pointers are the real documentation map. A quickstart titled Get started in 5 minutes and an overview tour live under web3py.readthedocs.io, hosted through the repository's .readthedocs.yaml, and release notes carry the change log. Implementation questions go to the Ethereum Python Community Discord, contributions start from a contributing guide and the Good First Issue label, and funding runs through GitHub sponsors of ApeWorX. pyproject.toml lists the Ethereum Foundation and the ApeWorX Collective as authors, with the ApeWorX Collective as maintainer. The licence is MIT, stated in both the README badge set and pyproject.toml.

Editorial conclusion

Adopt web3.py if your Ethereum work already lives in Python: contract calls, account handling and ENS resolution run in the same runtime as the rest of your code, installed with one pip command. Look elsewhere for browser-side integration, where a JavaScript library such as web3.js is the natural fit. Verify first that your interpreter lands in the supported 3.10 to 3.14 range, and that the v8.0.0 release notes in the documentation cover the interfaces you call.

Frequently asked questions

Official sources

1. ApeWorX/web3.py on GitHub
2. License: MIT
3. Project website
4. README
5. Releases