Buidler is a task runner that facilitates building Ethereum smart contracts. It helps developers manage and automate the recurring tasks that are inherent to the process of building smart contracts, 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.

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.

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 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

Global installation

Be careful about inconsistent behavior across different projects that use different Buidler versions.

npm install --global @nomiclabs/buidler

If you choose to install Buidler globally, you have to do the same for its plugins and their dependencies.

Quick Start

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

A barebones installation with no plugins allows you to compile your Solidity code, install plugins and create your own tasks.

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.0.0 👷‍‍

? 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 uses the buidler-truffle5, which makes Buidler compatible with tests built for Truffle. You can learn more about it in this guide. For now, all you need to know is that you may need to install some dependencies with

npm install --save-dev @nomiclabs/buidler-truffle5 @nomiclabs/buidler-web3 web3

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.0.0



  --config              A Buidler config file.
  --emoji               Use emoji in messages.
  --help                Shows this message.
  --network             The network to connect to. (default: "buidlerevm")
  --show-stack-traces   Show stack traces.
  --version             Shows buidler's version.


  accounts      Prints a list of the available 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
  run           Runs a user-defined script after compiling the project
  test          Runs mocha tests

To get help for a specific task run: 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 web3.eth.getAccounts();

  for (const account of accounts) {

module.exports = {};

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:

pragma solidity ^0.5.1;

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 @truffle/contract and Web3.js. You can use other libraries if you want, check the integrations described in our guides.

const Greeter = artifacts.require("Greeter");

// Traditional Truffle test
contract("Greeter", accounts => {
  it("Should return the new greeting once it's changed", async function() {
    const greeter = await Greeter.new("Hello, world!");
    assert.equal(await greeter.greet(), "Hello, world!");

    await greeter.setGreeting("Hola, mundo!");

    assert.equal(await greeter.greet(), "Hola, mundo!");

You can run your tests with npx buidler test

$ npx buidler test
Compiled 2 contracts successfully

  Contract: Greeter
Deploying a Greeter with greeting: Hello, world!
Changing greeting from 'Hello, world!' to 'Hola, mundo!'
    ✓ Should return the new greeting once it's changed (344ms)

  Greeter contract
Deploying a Greeter with greeting: Hello, world!
Deploying a Greeter with greeting: Hola, mundo!
      ✓ Should deploy with the right greeting (82ms)

  2 passing (434ms)

Deploying your contracts

Next, to deploy the contract we will use a Buidler script. Create a file deploy.js in scripts/ with the following code:

async function main() {
  const Greeter = artifacts.require("Greeter");

  const greeter = await Greeter.new("Hello, Buidler!");
  console.log("Greeter deployed to:", greeter.address);

  .then(() => process.exit(0))
  .catch(error => {

And run it with npx buidler run scripts/deploy.js:

$ npx buidler run scripts/deploy.js
All contracts have already been compiled, skipping compilation.
Greeter deployed to: 0x080f632fB4211CFc19d1E795F3f3109f221D44C9

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

For any questions or feedback you may have, you can find us in the Buidler Support Telegram group.

Last Updated: 2/28/2020, 11:04:00 AM