Quick Start


In the latest release, Ape requires:

  • Linux or macOS

  • Python 3.7.X or later


  1. Install Windows Subsystem Linux (WSL)

  2. Choose Ubuntu 20.04 OR Any other Linux Distribution with Python 3.7.X or later

Please make sure you are using Python 3.7.X or later.

Check your python command by entering

python3 --version


Suggestion: Create a virtual environment using virtualenv or venv. After creation and activating a virtual env.

You may skip this creating a virtual environment if you know you don’t require one for your use case.

Create your virtual environment folder

python3 -m venv /path/to/new/environment
source <venv_folder>/bin/activate

You should see (name_of_venv) DESKTOP_NAME:~/path:$. To deactivate the virtual environment, do:


Now that your Python version is later than 3.7.X and you have created a virtual environment. Let’s install Ape! There are 3 ways to install ape: pip, setuptools, or Docker.

via pip

You can install the latest release via pip:

pip install eth-ape

via setuptools

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

git clone https://github.com/ApeWorX/ape.git
cd ape
python3 setup.py install

via docker

Please visit our Dockerhub for more details on using Ape with Docker.

docker run \
--volume $HOME/.ape:/root/.ape \
--volume $HOME/.vvm:/root/.vvm \
--volume $HOME/.solcx:/root/.solcx \
--volume $PWD:/root/project \
--workdir /root/project \
apeworx/ape compile

Docker Uninstall Process: You will need to remove files generated by docker

sudo rm -rf **\~/.solcx**
sudo rm -rf **\~/.vvm**

Quick Usage

Use -h to list all the commands.

ape -h

You can import or generate accounts.

ape accounts import acc0   # Will prompt for a private key
ape accounts generate acc1

List all your accounts with the list command.

ape accounts list

Add any plugins you may need, such as vyper.

ape plugins list -a
ape plugins add vyper
ape plugins list -a

NOTE: If a plugin does not originate from the ApeWorX GitHub organization, you will get a warning about installing 3rd-class plugins. Any plugin that is not an official plugin has the chance of not being trustworthy. Thus, you should be mindful about which plugins you install. Additionally, plugins that come bundled with ape in the core installation cannot be removed and are considered part of the ape core software.

You can interact and compile contracts. Here is an example of a project with a contract you interact with:

git clone https://github.com/brownie-mix/vyper-token-mix.git
cd vyper-token-mix/

You can compile contracts within the contracts/ directory of your project. The --size option will display you the size of the contract.

ape compile --size

Provide the same arguments to pytest as you would to the ape test command.

ape test -k test_only_one_thing --coverage

Connect an IPython session through your favorite provider.

ape console --network ethereum:mainnet:infura

If you want to run specific files in a scripts/ directory, you can do it with using the ape run command.

# This command will run a file named deploy in the scripts/ directory
$ ape run deploy


To enable debug logging, run your command with the --verbosity flag using DEBUG as the value:

ape run --verbosity DEBUG

You can use ape as a package outside of scripts for the ape run command as well.

You can work with registered networks, providers, and blockchain ecosystems (like Ethereum):

from ape import networks
with networks.ethereum.mainnet.use_provider("infura"):
    ...  # Work with the infura provider here

You can work with test accounts, local accounts, and (WIP) popular hardware wallets:

from ape import accounts
a = accounts[0]  # Load by index
a = accounts["example.eth"]  # or load by ENS/address
a = accounts.load("alias") # or load by alias

You can also work with contract types:

from ape import project
c = a.deploy(project.MyContract, ...)
c.viewThis()  # Make Web3 calls
c.doThat(sender=a)  # Make Web3 transactions
assert c.MyEvent[-1].caller == a  # Search through Web3 events