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 Set up a clean environment.

Installation from source can be done from the root of the project with the following command.

$ pip install .

Using Web3

To use the web3 library you will need to initialize the Web3 class and connect to an Ethereum node. There are several ways to configure this connection; the full details can be found in the Providers documentation.

The quickest way to connect to a mainnet node for free is by setting up an account on Infura. On the Infura dashboard, create a project, copy the Project ID, then set the environment variable WEB3_INFURA_PROJECT_ID before running your script or application.


Use the web3.auto.infura module to connect to the Infura node.

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

This w3 instance will now allow you to interact with the Ethereum blockchain.


If you don’t want to use Infura, the web3.auto module is available and will guess at common node connection options.

>>> from web3.auto import w3
>>> w3.eth.blockNumber


If you get the result UnhandledRequest: No providers responded to the RPC request then you are not connected to a node. See Why do I need to connect to a node? and Choosing How to Connect to Your Node

Getting Blockchain Info

It’s time to start using Web3.py! Try getting all the information about the latest block.

>>> w3.eth.getBlock('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': []}

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.