Install & Compatibility
Where this runs
tested against v1.22.1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
7/8 runs
py 3.11
✕ build_error
7/8 runs
py 3.12
✕ build_error
7/8 runs
py 3.13
✕ build_error
7/8 runs
py 3.9
✕ build_error
✓ 19.5s
106MB installed
● package 106MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
project
✓ from brownie import project
Used to load the current Brownie project.
network
✓ from brownie import network
For connecting to and managing blockchain networks.
accounts
✓ from brownie import accounts
Provides access to local or connected blockchain accounts.
Contract
✓ from brownie import Contract
A factory for interacting with deployed contracts or abstract interfaces.
SimpleStorage
✓ from brownie import SimpleStorage
✗ from contracts.SimpleStorage import SimpleStorage
Compiled contracts are automatically exposed as top-level objects via the brownie import, assuming a project is loaded.
This quickstart demonstrates how to create a Brownie project, define a simple Solidity contract, deploy it to a local development network, and interact with its functions. It assumes a local blockchain (like Ganache or Hardhat) is running or can be launched by Brownie. Run `brownie init` and create the `SimpleStorage.sol` file as described in the comments before executing the Python script.
# 1. First, set up a Brownie project and a simple contract:
# $ brownie init simple_project
# $ cd simple_project
# $ mkdir contracts
# $ echo '// SPDX-License-Identifier: MIT\npragma solidity ^0.8.0;\ncontract SimpleStorage {\n uint256 public number;\n function store(uint256 _number) public { number = _number; }\n function retrieve() public view returns (uint256) { return number; }\n}' > contracts/SimpleStorage.sol
# $ mkdir scripts
# 2. Then, create scripts/deploy_and_interact.py with the following content:
from brownie import SimpleStorage, accounts, network
def main():
# Connect to a local development network (e.g., Ganache, Hardhat)
# If not already connected, Brownie will attempt to launch a local 'ganache-cli' fork
if not network.is_connected():
network.connect('development')
print(f"Active network: {network.show_active()}")
# Get the first available account for deployment
deployer = accounts[0]
print(f"Deploying from account: {deployer.address}")
# Deploy the SimpleStorage contract
print("Deploying SimpleStorage...")
simple_storage = SimpleStorage.deploy({"from": deployer})
print(f"SimpleStorage deployed at: {simple_storage.address}")
# Interact with the contract
initial_value = simple_storage.retrieve()
print(f"Initial stored value: {initial_value}")
new_value = 777
print(f"Storing new value: {new_value}")
tx = simple_storage.store(new_value, {"from": deployer})
tx.wait(1) # Wait for the transaction to be mined
updated_value = simple_storage.retrieve()
print(f"Updated stored value: {updated_value}")
# 3. Finally, run the script from your project root:
# $ brownie run scripts/deploy_and_interact.py --network development
brownie --version
Debug
Known issues
breakingUpcoming `web3.py` v7 upgrade in Brownie v1.22.x will break custom middleware integrations. If you use custom `web3.py` middleware, expect changes.fixReview `web3.py` v7 migration guide for middleware. Update Brownie middleware integration logic when upgrading to v1.22.0 stable.
affects: >=1.22.0 (pre-releases show this change)
breakingThe Etherscan API key handling changed in v1.21.0. Instead of network-specific environment variables (e.g., `ETHERSCAN_TOKEN_MAINNET`), a single `ETHERSCAN_TOKEN` variable is now used for all networks.fixConsolidate your Etherscan API keys into a single `ETHERSCAN_TOKEN` environment variable. Refer to Brownie documentation for details on environment variables.
affects: >=1.21.0
gotchaBrownie has strict Python version requirements. Version 1.21.0 requires Python >=3.10 and <4.fixEnsure you are using a compatible Python version (e.g., Python 3.10 or 3.11). Using Python 3.9 or 3.12+ will likely lead to installation or runtime errors.
affects: All versions >=1.21.0
gotchaSolidity compiler (solc) installation issues are common, especially when `py-solc-x` encounters download errors or requires a specific version not available on your system.fixManually install `solc` using `brownie solc install <version>` (e.g., `brownie solc install 0.8.0`). Ensure `py-solc-x` is up-to-date or compatible with your OS. For some systems, manual `solc` installation via system package managers might be required.
affects: All versions
Errors
Common errors & fixes
ValueError: No compatible Solc version installed.
Brownie cannot find a suitable Solidity compiler (solc) version for your contracts.
fixInstall the required solc version using `brownie solc install <version>` (e.g., `brownie solc install 0.8.0`). Check your project's `pragma` statements for the exact version needed.
ValueError: Network not connected. Please connect to a network prior to interacting with contracts.
Attempting to deploy or interact with contracts without an active blockchain network connection.
fixConnect to a network using `network.connect('development')` for a local test chain, or `network.connect('mainnet')` for a live network, before any blockchain interaction. AttributeError: 'BrownieContract' object has no attribute 'deploy'
Trying to deploy a contract using an *instance* of a compiled contract (e.g., `SimpleStorage().deploy()`) instead of the contract factory itself.
fixDeployment is done via the contract factory obtained from `brownie import` or `project.load()`. Correct usage is `SimpleStorage.deploy({'from': accounts[0]})` where `SimpleStorage` is the imported contract factory. TypeError: 'function' object is not subscriptable
Often occurs when attempting to call a contract method with arguments using incorrect Python syntax, treating the method as if it were a dictionary or list.
fixEnsure contract calls are made using `contract.method(arg1, arg2, {'from': account})` for transactions, or `contract.method(arg1, arg2).call()` for view/pure functions without transaction context. Avoid `contract.method[args]`. Upgrade
Version history
1.22.1latest on PyPI · released Jun 6, 2026
Audit
Dependencies
No dependency data recorded yet.