# Overview

Buidler is a task runner that facilitates building on Ethereum. It helps developers manage and automate the recurring tasks that are inherent to the process of building smart contracts and dApps, as well as easily introducing more functionality around this workflow. This means compiling and testing at the very core.

Buidler is designed around the concepts of tasks and plugins. Every time you're running Buidler from the CLI you're running a task. E.g. npx buidler compile is running the compile task. Tasks can call other tasks, allowing complex workflows to be defined. Users and plugins can override existing tasks, making those workflows customizable and extendable.

The bulk of Buidler's functionality comes from plugins, which as a developer you're free to choose the ones you want to use. Buidler is unopinionated in terms of what tools you end up using, but it does come with some built-in defaults. All of which can be overriden.

Buidler comes built-in with Buidler EVM, a local Ethereum network designed for development.

# Installation

The recommended way of using Buidler is through a local installation in your project. This way your environment will be reproducible and you will avoid future version conflicts. To use it in this way you will need to prepend npx to run it (i.e. npx buidler). To install locally initialize your npm project using npm init and follow the instructions. Once ready run:

npm install --save-dev @nomiclabs/buidler

# Quick Start

This guide will explore the basics of creating a Buidler project.

A barebones installation with no plugins allows you to create your own tasks, compile your Solidity code, run your tests and run a local development network you can deploy your contracts to (Buidler EVM).

To create your Buidler project run npx buidler in your project folder:

$ npx buidler
888               d8b      888 888
888               Y8P      888 888
888                        888 888
88888b.  888  888 888  .d88888 888  .d88b.  888d888
888 "88b 888  888 888 d88" 888 888 d8P  Y8b 888P"
888  888 888  888 888 888  888 888 88888888 888
888 d88P Y88b 888 888 Y88b 888 888 Y8b.     888
88888P"   "Y88888 888  "Y88888 888  "Y8888  888

👷 Welcome to Buidler v1.3.3 👷‍‍

? What do you want to do? …
❯ Create a sample project
  Create an empty buidler.config.js

Let’s create the sample project and go through the steps to try out the sample task and compile, test and deploy the sample contract.

The sample project will ask you to install buidler-waffle and buidler-ethers, which makes Buidler compatible with tests built with Waffle. You can learn more about it in this guide.


Buidler will let you know how, but in case you missed it you can install them with npm install --save-dev @nomiclabs/buidler-waffle ethereum-waffle chai @nomiclabs/buidler-ethers ethers

# Running tasks

To first get a quick sense of what's available and what's going on, run npx buidler in your project folder:

$ npx buidler
Buidler version 1.3.3



  --config            A Buidler config file. 
  --emoji             Use emoji in messages. 
  --help              Shows this message, or a task's help if its name is provided 
  --max-memory        The maximum amount of memory that Buidler can use. 
  --network           The network to connect to. 
  --show-stack-traces Show stack traces. 
  --verbose           Enables Buidler verbose logging 
  --version           Shows buidler's version. 


  accounts  Prints the list of accounts
  clean     Clears the cache and deletes all artifacts
  compile   Compiles the entire project, building all artifacts
  console   Opens a buidler console
  flatten   Flattens and prints all contracts and their dependencies
  help      Prints this message
  node      Starts a JSON-RPC server on top of Buidler EVM
  run       Runs a user-defined script after compiling the project
  test      Runs mocha tests

To get help for a specific task run: npx buidler help [task]

This is the list of built-in tasks, and the sample accounts task. Further ahead, when you start using plugins to add more functionality, tasks defined by those will also show up here. This is your starting point to find out what tasks are available to run.

If you take a look at buidler.config.js, you will find the definition of the task accounts:



// This is a sample Buidler task. To learn how to create your own go to
// https://buidler.dev/guides/create-task.html
task("accounts", "Prints the list of accounts", async () => {
  const accounts = await ethers.getSigners();

  for (const account of accounts) {
    console.log(await account.getAddress());

// You have to export an object to set up your config
// This object can have the following optional entries:
// defaultNetwork, networks, solc, and paths.
// Go to https://buidler.dev/config/ to learn more
module.exports = {
  // This is a sample solc configuration that specifies which version of solc to use
  solc: {
    version: "0.6.8",

To run it, try npx buidler accounts:

$ npx buidler accounts

# Compiling your contracts

Next, if you take a look at contracts/, you should be able to find Greeter.sol:

//SPDX-License-Identifier: Unlicense
pragma solidity ^0.6.8;

import "@nomiclabs/buidler/console.sol";

contract Greeter {
  string greeting;

  constructor(string memory _greeting) public {
    console.log("Deploying a Greeter with greeting:", _greeting);
    greeting = _greeting;

  function greet() public view returns (string memory) {
    return greeting;

  function setGreeting(string memory _greeting) public {
    console.log("Changing greeting from '%s' to '%s'", greeting, _greeting);
    greeting = _greeting;

To compile it, simply run:

npx buidler compile

# Testing your contracts

The sample project comes with these tests that use Waffle and Ethers.js. You can use other libraries if you want, check the integrations described in our guides.

const { expect } = require("chai");

describe("Greeter", function() {
  it("Should return the new greeting once it's changed", async function() {
    const Greeter = await ethers.getContractFactory("Greeter");
    const greeter = await Greeter.deploy("Hello, world!");
    await greeter.deployed();
    expect(await greeter.greet()).to.equal("Hello, world!");

    await greeter.setGreeting("Hola, mundo!");
    expect(await greeter.greet()).to.equal("Hola, mundo!");

You can run your tests with npx buidler test

$ npx buidler test
Compiled 2 contracts successfully

  Contract: Greeter
    ✓ Should return the new greeting once it's changed (762ms)

  1 passing (762ms)

# Deploying your contracts

Next, to deploy the contract we will use a Buidler script. Inside scripts/ you will find sample-script.js with the following code:

// We require the Buidler Runtime Environment explicitly here. This is optional 
// but useful for running the script in a standalone fashion through `node <script>`.
// When running the script with `buidler run <script>` you'll find the Buidler
// Runtime Environment's members available in the global scope.
const bre = require("@nomiclabs/buidler");

async function main() {
  // Buidler always runs the compile task when running scripts through it. 
  // If this runs in a standalone fashion you may want to call compile manually 
  // to make sure everything is compiled
  // await bre.run('compile');

  // We get the contract to deploy
  const Greeter = await ethers.getContractFactory("Greeter");
  const greeter = await Greeter.deploy("Hello, Buidler!");

  await greeter.deployed();

  console.log("Greeter deployed to:", greeter.address);

// We recommend this pattern to be able to use async/await everywhere
// and properly handle errors.
  .then(() => process.exit(0))
  .catch(error => {

Run it with npx buidler run scripts/sample-script.js:

$ npx buidler run scripts/sample-script.js
All contracts have already been compiled, skipping compilation.
Deploying a Greeter with greeting: Hello, Buidler!
Greeter deployed to: 0x7c2C195CD6D34B8F845992d380aADB2730bB9C6F

# Connecting a wallet or Dapp to Buidler EVM

Buidler will always spin up an in-memory instance of Buidler EVM on startup by default, but it's also possible to run Buidler EVM in a standalone fashion so that external clients can connect to it through localhost. This could be MetaMask, your Dapp front-end, or a script.

To run Buidler EVM in this way, run npx buidler node:

$ npx buidler node
Started HTTP and WebSocket JSON-RPC server at

This will expose a JSON-RPC interface to Buidler EVM. To use it connect your wallet or application to http://localhost:8545.

If you want to connect Buidler to this node to, for example, run a deployment script against it, you simply need to run it using --network localhost.

To try this, start a node with npx buidler node and re-run the sample script using the network option:

npx buidler run scripts/sample-script.js --network localhost

Congrats! You have created a project, ran a Buidler task, compiled a smart contract, installed a Waffle integration plugin, wrote and ran a test using the Waffle and ethers.js plugins, and deployed a contract.

If you need help, find us in the Buidler Support Discord server.

Last Updated: 9/4/2020, 8:38:45 PM