Quickstart

Note

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.

Installation

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

$ pip install web3

Note

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. The quickest way to do so for free is by setting up an account on Infura. On Infura, create a project and copy the Project ID. Then set the environment variable WEB3_INFURA_PROJECT_ID.

$ export WEB3_INFURA_PROJECT_ID=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

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

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

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

Note

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
4000000

Note

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().

Note

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.