Pypi Status Build Status Docs Status Coverage Status

Brownie is a Python-based development and testing framework for smart contracts targeting the Ethereum Virtual Machine.




via pipx

The recommended way to install Brownie is via pipx. pipx installs Brownie into a virtual environment and makes it available directly from the commandline. Once installed, you will never have to activate a virtual environment prior to using Brownie.

To install pipx:

python3 -m pip install --user pipx
python3 -m pipx ensurepath

To install Brownie using pipx:

pipx install eth-brownie

To upgrade to the latest version:

pipx upgrade eth-brownie

via pip

You can install the latest release via pip:

pip install eth-brownie

via setuptools

You can clone the repository and use setuptools for the most up-to-date version:

git clone
cd brownie
python3 install

Quick Usage

To initialize a new Brownie project, start by creating a new folder. From within that folder, type:

brownie init

Next, type brownie --help for basic usage information.

Documentation and Support

Brownie documentation is hosted at Read the Docs.

If you have any questions about how to use Brownie, feel free to ask on Ethereum StackExchange or join us on Gitter.


To run the tests, first install the developer dependencies:

pip install -r requirements-dev.txt

Then use tox to run the complete suite against the full set of build targets, or pytest to run tests against a specific version of Python. If you are using pytest you must include the -p no:pytest-brownie flag to prevent it from loading the Brownie plugin.

Using Docker

You can use a sandbox container provided in the docker-compose.yml file for testing inside a Docker environment.

This container provides everything you need to test using a Python 3.6 interpreter.

Start the test environment:

docker-compose up -d

To open a session to the container:

docker-compose exec sandbox bash

To run arbitrary commands, use the bash -c prefix.

docker-compose exec sandbox bash -c ''

For example, to run the tests in brownie/tests/

docker-compose exec sandbox bash -c 'python -m pytest tests/convert/'


Help is always appreciated! Feel free to open an issue if you find a problem, or a pull request if you've solved an issue.

Please check out our Contribution Guide prior to opening a pull request, and join the Brownie Gitter channel if you have any questions.


This project is licensed under the MIT license.