Installing Brownie

The recommended way to install Brownie is via pipx. Pipx is a tool to help you install and run end-user applications written in Python. It’s roughly similar to macOS’s brew, JavaScript’s npx, and Linux’s apt.

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.

pipx does not ship with Python. If you have not used it before you will probably need to install it.

To install pipx:

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


You may need to restart your terminal after installing pipx.

To install Brownie using pipx:

pipx install eth-brownie

Once installation is complete, type brownie to verify that it worked:

$ brownie
Brownie - Python development framework for Ethereum

Usage:  brownie <command> [<args>...] [options <args>]

Other Installation Methods

You can also install Brownie via pip, or clone the repository and use setuptools. If you install via one of these methods, we highly recommend using venv and installing into a virtual environment.

To install via pip:

pip install eth-brownie

To clone the github repository and install via setuptools:

git clone
cd brownie
python3 install


Brownie has the following dependencies:


The Brownie GUI is built using the Tk GUI toolkit. Both Tk and tkinter are available on most Unix platforms, as well as on Windows systems.

Tk is not a strict dependency for Brownie. However, if it is not installed on your system you will receive an error when attempting to load the GUI.

You can use the following command to check that Tk has been correctly installed:

python -m tkinter

This should open a simple window and display the installed version number.

For installation instructions read Installing TK within the TK Documentation.

Using Brownie with Hardhat

Hardhat is an Ethereum development environment with similar functionality to Brownie. Hardhat includes the Hardhat Network, a local development node similar to Ganache. The Hardhat Network may be used as an alternative to Ganache within Brownie.


Hardhat integration within Brownie is a new feature and still under development. Functionality should be on-par with Ganache, however there may still be bugs. Please open an issue on Github if you run into any inconsistencies or missing functionality.

To use the Hardhat network with Brownie you must first install Hardhat. This can either be done in the root directory of each Brownie project, or once in your home directory:

npm install --save-dev hardhat

See the Hardhat documentation for more information on installing Hardhat.

Once installed, include the --network hardhat flag to run Brownie with Hardhat. For example, to launch the console:

brownie console --network hardhat

The first time you use Hardhat within a Brownie project, a hardhat.config.js configuration file is generated. You should not modify any of the settings within this file as they are required for compatibility.

If you have updated your brownie version from older versions, hardhat networks will be missing. You have to update ~/.brownie/network-config.yaml. It can be updated using the one here