All code starting with a $ is meant to run on your terminal. All code starting with a >>> is meant to run in a python interpreter, like ipython.


web3.py can be installed (preferably in a virtualenv) using pip as follows:

$ pip install web3


If you run into problems during installation, you might have a broken environment. See the troubleshooting guide to setting up a clean environment.

Using Web3

This library depends on a connection to an Ethereum node. We call these connections Providers and there are several ways to configure them. The full details can be found in the Providers documentation. This Quickstart guide will highlight a couple of the most common use cases.

Test Provider

If you’re just learning the ropes or doing some quick prototyping, you can use a test provider, eth-tester. This provider includes some accounts prepopulated with test ether and instantly includes each transaction into a block. web3.py makes this test provider available via EthereumTesterProvider.


The EthereumTesterProvider requires additional dependencies. Install them via pip install "web3[tester]", then import and instantiate the provider as seen below.

>>> from web3 import Web3, EthereumTesterProvider
>>> w3 = Web3(EthereumTesterProvider())
>>> w3.is_connected()

Local Providers

The hardware requirements are steep, but the safest way to interact with Ethereum is to run an Ethereum client on your own hardware. For locally run nodes, an IPC connection is the most secure option, but HTTP and websocket configurations are also available. By default, the popular Geth client exposes port 8545 to serve HTTP requests and 8546 for websocket requests. Connecting to this local node can be done as follows:

>>> from web3 import Web3, AsyncWeb3

# IPCProvider:
>>> w3 = Web3(Web3.IPCProvider('./path/to/filename.ipc'))
>>> w3.is_connected()

# HTTPProvider:
>>> w3 = Web3(Web3.HTTPProvider(''))
>>> w3.is_connected()

# AsyncHTTPProvider:
>>> w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider(''))
>>> await w3.is_connected()

# -- Persistent Connection Providers -- #

# WebSocketProvider:
>>> w3 = await AsyncWeb3(AsyncWeb3.WebSocketProvider('ws://'))
>>> await w3.is_connected()

# AsyncIPCProvider:
>>> w3 = await AsyncWeb3(AsyncWeb3.AsyncIPCProvider('./path/to/filename.ipc'))
>>> await w3.is_connected()

Remote Providers

The quickest way to interact with the Ethereum blockchain is to use a remote node provider. You can connect to a remote node by specifying the endpoint, just like the previous local node example:

>>> from web3 import Web3, AsyncWeb3

>>> w3 = Web3(Web3.HTTPProvider('https://<your-provider-url>'))

>>> w3 = AsyncWeb3(AsyncWeb3.AsyncHTTPProvider('https://<your-provider-url>'))

>>> w3 = await AsyncWeb3(AsyncWeb3.WebSocketProvider('wss://<your-provider-url>'))

This endpoint is provided by the remote node service, typically after you create an account.

Getting Blockchain Info

It’s time to start using web3.py! Once properly configured, the w3 instance will allow you to interact with the Ethereum blockchain. Try getting all the information about the latest block:

>>> w3.eth.get_block('latest')
{'difficulty': 1,
 'gasLimit': 6283185,
 'gasUsed': 0,
 'hash': HexBytes('0x53b983fe73e16f6ed8178f6c0e0b91f23dc9dad4cb30d0831f178291ffeb8750'),
 'logsBloom': HexBytes('0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000'),
 'miner': '0x0000000000000000000000000000000000000000',
 'mixHash': HexBytes('0x0000000000000000000000000000000000000000000000000000000000000000'),
 'nonce': HexBytes('0x0000000000000000'),
 'number': 0,
 'parentHash': HexBytes('0x0000000000000000000000000000000000000000000000000000000000000000'),
 'proofOfAuthorityData': HexBytes('0x0000000000000000000000000000000000000000000000000000000000000000dddc391ab2bf6701c74d0c8698c2e13355b2e4150000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000'),
 'receiptsRoot': HexBytes('0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421'),
 'sha3Uncles': HexBytes('0x1dcc4de8dec75d7aab85b567b6ccd41ad312451b948a7413f0a142fd40d49347'),
 'size': 622,
 'stateRoot': HexBytes('0x1f5e460eb84dc0606ab74189dbcfe617300549f8f4778c3c9081c119b5b5d1c1'),
 'timestamp': 0,
 'totalDifficulty': 1,
 'transactions': [],
 'transactionsRoot': HexBytes('0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421'),
 'uncles': []}

web3.py can help you read block data, sign and send transactions, deploy and interact with contracts, and a number of other features.

A few suggestions from here:

  • The Overview page provides a summary of web3.py’s features.

  • The w3.eth API contains the most frequently used methods.

  • A guide to Contracts includes deployment and usage examples.

  • The nuances of Transactions are explained in another guide.


It is recommended that your development environment have the PYTHONWARNINGS=default environment variable set. Some deprecation warnings will not show up without this variable being set.