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.

Provider: Local Geth Node

For locally run nodes, an IPC connection is the most secure option, but HTTP and websocket configurations are also available. By default, Geth 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

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

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

# WebsocketProvider:
>>> w3 = Web3(Web3.WebsocketProvider('ws://'))

>>> w3.isConnected()

If you stick to the default ports or IPC file locations, you can utilize a convenience method to automatically detect the provider and save a few keystrokes:

>>> from web3.auto import w3
>>> w3.isConnected()

Provider: Infura

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

>>> from web3 import Web3
>>> w3 = Web3(Web3.HTTPProvider('https://mainnet.infura.io/v3/<infura-project-id>'))

This endpoint is provided by Infura after you create a (free) account.

Again, a convenience method exists to save a few keystrokes:

>>> from web3.auto.infura import w3
>>> w3.eth.block_number

Note that this requires your Infura Project ID to be set as the environment variable WEB3_INFURA_PROJECT_ID before running your script or application:


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.

Many of the typical things you’ll want to do will be in the w3.eth API, so that is a good place to start.

If you want to dive straight into contracts, check out the section on Contracts, including a Contract Deployment Example, and how to create a contract instance using w3.eth.contract().


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.