Deployment Basics

Once your project is ready to be deployed to a persistent chain (such as the Etherem mainnet or a testnet), Brownie can be used to handle the deployments.

It is important to remember that blockchains are permanent and immutable. Once your project has been deployed there is no going back. For this reason, we highly recommend the following process when deploying to the mainnet:

  1. Create a deployment script
  2. Test the script on your local development environment
  3. Test the script again on one of the public test networks and verify that it executed as intended
  4. Use the script to deploy your project to the mainnet

Once deployment is complete you may also create an ethPM package to simplify the process for other developers who wish to interact with your project.

Writing a Deployment Script

Deployment scripts function in the same way as any other Brownie script, but there are a couple of things to keep in mind when writing one for a non-local network:

  1. Unless you are using your own node you will have to unlock a local account prior to deploying. This is handled within the script by calling Accounts.load. If you have not yet added a local account to Brownie, read the documentation on local account management.
  2. Most networks require that you to pay gas to miners. If no values are specified Brownie will calculate the gas price and limit automatically, but in some cases you may wish to manually declare these values.

Here is an small example script that unlocks a local account and uses it to deploy a Token contract.

from brownie import Token, accounts

def main():
    acct = accounts.load('deployment_account')
    Token.deploy("My Real Token", "RLT", 18, 1e28, {'from': acct})

Running your Deployment Script

In order to execute your script in a live environment, you must include the --network flag in the command line. For example, to connect to the ropsten network and run scripts/

$ brownie run --network ropsten

Remember that transactions are not confirmed immediately on live networks. You will see a notification on the status of each transaction, however the script will take some time to complete.

See the documentation on network management for more information on how to define and connect to live networks.

The Deployment Map

Brownie will maintain a map.json file in your build/deployment/ folder that lists all deployed contracts on live networks, sorted by chain and contract name.

  "1": {
    "SolidityStorage": [
    "VyperStorage": [

The list for each contract is sorted by the block number of the deployment with the most recent deployment first.

Interacting with Deployed Contracts

Brownie saves information about contract deployments on live networks. Once a contract has been deployed, the generated ProjectContract instance will still be available in future Brownie sessions.

The following actions will NOT remove locally stored deployment data:

  • Disconnecting and reconnecting to the same network
  • Closing and reloading a project
  • Exiting and reloading Brownie
  • Modifying a contract’s source code - Brownie still retains the source for the deployed version

The following actions WILL remove locally stored deployment data within your project:

  • Calling ContractContainer.remove will erase deployment information for the removed ProjectContract instances.
  • Removing or renaming a contract source file within your project will cause Brownie to delete all deployment information for the removed contract.
  • Deleting the build/deployments/ directory will erase all information about deployed contracts.

To restore a deleted ProjectContract instance, or generate one for a deployment that was handled outside of Brownie, use the method.

Saving Deployments on Development Networks

If you need deployment artifacts on a development network, set dev_deployment_artifacts to true in the in the project’s brownie-config.yaml file.

These temporary deployment artifacts and the corresponding entries in the deployment map will be removed whenever you (re-) load a project or connect, disconnect, revert or reset your local network.

If you use a development network that is not started by brownie - for example an external instance of ganache - the deployment artifacts will not be deleted when disconnecting from that network. However, the network will be reset and the deployment artifacts deleted when you connect to such a network with brownie.