Ape Framework is an easy-to-use Web3 development tool. Users can compile, test, and interact with smart contracts all in one command line session. With our modular plugin system, Ape supports multiple contract languages and chains.
Ape is built by ApeWorX LTD.
Join our ApeWorX Discord server to stay up to date on new releases, plugins and tutorials.
If you want to just get started, jump down to the Playing with Ape.
Read our technical documentation to get a deeper understanding of our open source Framework.
Read our academic platform will help you master Ape Framework with tutorials and challenges.
In the latest release, Ape requires:
Linux or macOS
Python 3.8 up to 3.11
Windows: Install Windows Subsystem Linux (WSL)
Check your python version in a terminal with
There are three ways to install ape:
Considerations for Installing:
pip, we advise using the most up-to-date version of
pipto increase the chance of a successful installation.
See issue https://github.com/ApeWorX/ape/issues/1558.
pipfrom the command line, run:
pip install --upgrade pip.
We advise installing
apewith recommended plugins
pip install eth-ape'[recommended-plugins]'.
We advise for macOS users to install virtual env via homebrew.
Ape can also run in a docker container.
Please visit our Dockerhub for more details on using Ape with Docker.
docker run \ --volume $HOME/.ape:/home/harambe/.ape \ --volume $HOME/.vvm:/home/harambe/.vvm \ --volume $HOME/.solcx:/home/harambe/.solcx \ --volume $PWD:/home/harambe/project \ apeworx/ape compile
Playing with Ape
After you installed Ape, you can run
ape --version to make sure it works and is the latest version.
There are two ways to interact with Ape:
Ape is both a CLI tool and a Python SDK.
The CLI tool contains all the Ape commands and the Python SDK contains the classes and types needed to compose scripts, console actions, and tests.
Ape Modular Plugin System:
Our list of plugins is the best way to have the most interoperable experience with Web3.
NOTE: If a plugin does not originate from the ApeWorX GitHub Organization, you will get a warning about installing 3rd-party plugins.
Install 3rd party plugins at your own risk.
Additionally, plugins that come bundled with
ape in the core installation cannot be removed and are part of the
ape core software.
Learn more about installing plugins from following this installing user guide.
Learn more about developing your own plugins from this developing user guide.
In Ape, you will need accounts to make transactions.
You can import or generate accounts using the core
ape accounts import acc0 # Will prompt for a private key ape accounts generate acc1
List all your accounts with the
ape accounts list
Learn more about accounts in Ape by following the accounts guide.
Add any plugins you may need, such as
ape plugins list -a ape plugins install vyper ape plugins list -a
When using Ape, you generally will work with a project.
Learn more about smart-contract projects from this projects guide.
You can compile contracts within the
contracts/ directory of your project.
--size option will display you the size of the contract.
ape compile --size
Learn more about compiling in Ape by following the compile guide.
Use Ape to test your smart-contract projects.
Provide the same arguments to
pytest as you would to the
ape test command.
ape test -k test_only_one_thing
Visit the testing guide to learn more about testing using Ape.
Ape provides an
IPython interactive console with useful pre-defined locals to interact with your project.
To interact with a deployed contract in a local environment, start by opening the console:
ape console --network ethereum:mainnet:infura
Visit Ape Console to learn how to use Ape Console.
If you want to run specific files in a
scripts/ directory, you can do it using the
ape run command.
# This command will run a file named deploy in the scripts/ directory $ ape run deploy
Learn more about scripting using Ape by following the scripting guide.
To enable debug logging, run your command with the
--verbosity flag using
DEBUG as the value:
ape --verbosity DEBUG run
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
To learn more about networks in Ape, see this guide.