web3.py: a Python interface to Ethereum, and what to check before adopting v8.0.0
A python interface for interacting with the Ethereum blockchain and ecosystem.
At a glance
- What is it?
- web3.py is the Python library for reading Ethereum state, sending transactions and calling contracts. It installs with pip, supports Python 3.10 and later, and ships under the MIT licence.
- Who is it for?
- Adopt web3.py when your Ethereum access is written in Python: scripts, indexers, back-office jobs, test suites. Do not adopt it if your team works in TypeScript or you need a browser-side wallet integration, because the JavaScript ecosystem is where those pieces live.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 22 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 21, 2026, and from our analysis. They are not legal advice.
Star history
- ApeWorX/web3.py5,542 ★ · +9
| Repository | 2026-09-23 | 2026-11-21 |
|---|---|---|
| ApeWorX/web3.py | 5.5k | 5.5k |
9 Stars in the last 59 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
What web3.py is for, and who ends up using it
Ethereum nodes speak JSON-RPC. Every read of a balance, every estimate of gas, every contract call is a JSON payload sent over HTTP, WebSocket or IPC, and the response is JSON back. Writing that by hand is possible and unpleasant: you have to encode function selectors, pack arguments into ABI-encoded hex, decode the return value, and track nonces for anything that writes. web3.py exists to absorb that work. The README describes it as a library that "allows you to interact with the Ethereum blockchain using Python, enabling you to build decentralized applications, interact with smart contracts, and much more." The audience is Python developers: people writing data pipelines that read chain state, backend services that submit transactions, and test suites that need a local chain to run against. If your codebase is already Python and you need chain access inside it, this is the library the Python Ethereum community converged on. The package metadata lists the Ethereum Foundation and the ApeWorX Collective as authors, with ApeWorX as maintainer.
How the library sits between your code and a node
The architecture is a provider layer under a Web3 object. You construct a Web3 instance with a provider, and that provider owns the transport: HTTP via requests, WebSocket via websockets, or a local process connection. Calls on the Web3 object and on contract objects are translated into JSON-RPC requests and handed to the provider. The dependency list in pyproject.toml shows the split clearly: aiohttp and requests for transport, websockets for the streaming case, eth-abi for encoding and decoding contract data, eth-account for key handling and signing, eth-utils and eth-typing for the shared primitives, hexbytes for byte handling, and pydantic. That means web3.py does not run a node and does not hold chain state. It is a client. Everything you ask it is answered by whatever node you point it at, so the correctness of your results depends on that node being synced and honest. The repository also carries a separate ens/ directory alongside web3/, which reflects that ENS resolution is developed as its own package area rather than being folded into the core module tree.
Installing web3.py and making a first call
The README gives one installation command. It requires Python 3.10 or later; pyproject.toml sets requires-python to ">=3.10,<4" and the classifiers list 3.10 through 3.14.
python -m pip install web3After that, the README points to a "Get started in 5 minutes" quickstart and an overview tour in the documentation. The repository does not print a worked connection example in the README itself, so the exact provider constructor for your node belongs to the docs, not to this page. What the dependency list does suggest is the transport libraries in use: requests and aiohttp for HTTP, and websockets for WebSocket. For a first real use, the shape is always the same. You create a Web3 instance bound to a provider, then read something that requires no key, such as the latest block number or an account balance. Reads need no signing and no funds. Writes do, and they need an unlocked account or a local private key, which is where eth-account comes in.
The test setup is part of the repository, not an afterthought
Two files at the top level matter if you plan to run the project's own tests or write against a simulated chain. The Dockerfile builds from python:3.13, copies web3/, tests/ and ens/, installs uv, and runs uv sync --all-extras --all-groups. The docker-compose.yml defines a single sandbox service that builds from that Dockerfile, mounts the repository at /code, and runs tail -f /dev/null, which keeps the container alive so you can exec into it. That is a development environment, not a deployment artifact. It is also the clearest signal of how the maintainers expect contributors to work: a container with every dependency group installed, rather than a virtualenv you assemble by hand. The optional dependency group named tester pulls in eth-tester with py-evm, which is the in-process simulated chain used for testing contract logic without a real node. If you are evaluating web3.py for a project that needs deterministic tests, that extra is the relevant piece, and it is opt-in: a plain pip install web3 does not bring it.
Where web3.py is the wrong choice
web3.py assumes a node. There is no light client, no embedded chain, and no fallback if the endpoint you configured stops responding. If your application must keep working when a third-party RPC provider rate-limits you, the library will not solve that; you have to run your own node or build failover across providers yourself. The README does not document rollback, retry policy or provider failover, so treat those as your responsibility. A second boundary is versioning. The most recent release is v8.0.0. Major versions of a library this central to signing and encoding are not cosmetic; the README directs readers to the change log at web3py.readthedocs.io for release notes, and that is where migration detail lives. Pinning loosely and upgrading casually is how you get a broken signing path in production. Third, the library is Python-only by design. If your product is a browser wallet or a TypeScript frontend, this is the wrong tool and no amount of interop will make it the right one.
web3.py versus web3.js: same protocol, different ecosystem
The comparison people actually search for is web3.py against web3.js. Both are clients for the same JSON-RPC protocol, so the difference is not in what the chain will let you do; it is in where the code runs and what surrounds it. web3.js lives in the JavaScript ecosystem, which is where browser wallet injection, front-end frameworks and most dapp tooling sit. web3.py lives in Python, which is where data engineering, scripting, backend services and quantitative analysis sit. If your job is to pull chain data into a warehouse, orchestrate transactions from a server, or write contract tests in pytest, the Python library fits the surrounding code. If your job is to render a wallet connection in a browser, the JavaScript library fits. Choosing between them is choosing a runtime, not a feature set. The dependency list makes the Python side concrete: requests, aiohttp, websockets, eth-abi, eth-account, pydantic. That is a server-side stack.
Licence, maintenance and upgrade cost
The licence is MIT, declared both in pyproject.toml and in the repository's LICENSE file. MIT is permissive: it allows commercial use and modification with attribution and without copyleft obligations on your own code. That is a statement about the licence text, not legal advice, and if you are shipping in a regulated environment you should read the file yourself. On maintenance, the repository is not archived and the last push was on 2026-10-30, and the v8.0.0 release is dated 2026-08-31. The only release listed is a major version, v8.0.0. For adopters that cuts both ways. You get a stable surface for long stretches, and you get migration work concentrated into single upgrade events. Budget for reading the release notes before you bump the pin, and check whether your transitive dependencies (eth-abi, eth-account, eth-typing, eth-utils) moved in lockstep, because those are declared with minimum versions rather than exact pins.
Editorial conclusion
Adopt web3.py when your Ethereum access is written in Python: scripts, indexers, back-office jobs, test suites. Do not adopt it if your team works in TypeScript or you need a browser-side wallet integration, because the JavaScript ecosystem is where those pieces live. Before committing, check the release notes for v8.0.0 against your pinned dependencies, since the project's own change log is the only place migration steps are recorded, and confirm that your provider setup (HTTP, WebSocket or IPC) matches what the docs describe for your environment.
Frequently asked questions
How do I install web3.py?
Run python -m pip install web3. The package requires Python 3.10 or later, and the README points to a quickstart guide in the documentation for the first steps after installation.
What is web3.py?
It is a Python library for interacting with the Ethereum blockchain. The README describes it as enabling you to build decentralized applications, interact with smart contracts, and more, and it is published under the MIT licence.
What is Web3 py?
Web3.py is a Python interface to Ethereum, distributed as the web3 package on PyPI. It sits between your Python code and a node, translating calls into JSON-RPC requests over HTTP, WebSocket or IPC.
Is there an alternative to web3.py?
The closest alternative in practice is web3.js, which targets the same JSON-RPC protocol from the JavaScript ecosystem. The choice between them is mostly about which runtime your surrounding code already uses.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/apeworx-web3-py)Star history chart for your README
[](https://hysenlabs.com/projects/apeworx-web3-py)Was this useful?