The provider is how web3 talks to the blockchain. Providers take JSON-RPC requests and return the response. This is normally done by submitting the request to an HTTP or IPC socket based server.
Note
web3.py supports one provider per instance. If you have an advanced use case that requires multiple providers, create and configure a new web3 instance per connection.
If you are already happily connected to your Ethereum node, then you can skip the rest of the Providers section.
Most nodes have a variety of ways to connect to them. If you have not decided what kind of node to use, head on over to choosing_node
The most common ways to connect to your node are:
- IPC (uses local filesystem: fastest and most secure)
- Websockets (works remotely, faster than HTTP)
- HTTP (more nodes support it)
If you're not sure how to decide, choose this way:
- If you have the option of running web3.py on the same machine as the node, choose IPC.
- If you must connect to a node on a different computer, use Websockets.
- If your node does not support Websockets, use HTTP.
Most nodes have a way of "turning off" connection options. We recommend turning off all connection options that you are not using. This provides a safer setup: it reduces the number of ways that malicious hackers can try to steal your ether.
Once you have decided how to connect, you specify the details using a Provider. Providers are web3.py classes that are configured for the kind of connection you want.
See:
~web3.providers.ipc.IPCProvider
~web3.providers.websocket.WebsocketProvider
~web3.providers.rpc.HTTPProvider
~web3.providers.async_rpc.AsyncHTTPProvider
Once you have configured your provider, for example:
from web3 import Web3
my_provider = Web3.IPCProvider('/my/node/ipc/path')
Then you are ready to initialize your Web3 instance, like so:
w3 = Web3(my_provider)
Finally, you are ready to get started with web3.py<first_w3_use>
.
Alternatively, you can set the environment variable WEB3_PROVIDER_URI
before starting your script, and web3 will look for that provider first.
Valid formats for this environment variable are:
file:///path/to/node/rpc-json/file.ipc
http://192.168.1.2:8545
https://node.ontheweb.com
ws://127.0.0.1:8546
To connect to a geth --dev
Proof of Authority instance with defaults:
>>> from web3.auto.gethdev import w3
# confirm that the connection succeeded
>>> w3.is_connected()
True
Web3 ships with the following providers which are appropriate for connecting to local and remote JSON-RPC servers.
~web3.providers.auto.AutoProvider
is the default used when initializing web3.Web3
without any providers. There's rarely a reason to use it explicitly.
Warning
Experimental: This provider is experimental. There are still significant gaps in functionality. However it is being actively developed and supported.
Note
To install the needed dependencies to use EthereumTesterProvider, you can install the pip extras package that has the correct interoperable versions of the eth-tester
and py-evm
dependencies needed to do testing: e.g. pip install web3[tester]