Getting started

In this guide, we’ll explore how to start using Buidler in your Ethereum project.

What makes Buidler special? What can you achieve with it?

Buidler allows you to streamline your development workflow by making it easy to incorporate other tools into your process, as well as granting you all the flexibility you need to adapt the tools to your exact needs. What dependencies and tools you use is up to you. Buidler will only help you orchestrate them.

Out of the box, you can compile your Solidity code, install plugins and create your own tasks.

Let’s install it to try it out:

npm install @nomiclabs/buidler

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

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

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-beta.10



  --config              A Buidler config file.
  --emoji               Use emoji in messages.
  --help                Shows this message.
  --network             The network to connect to. (default: "develop")
  --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:

task("accounts", "Prints a list of the available accounts", async () => {
  const accounts = await ethereum.send("eth_accounts");

  console.log("Accounts:", accounts);

module.exports = {};

NOTE: in the Buidler 1.0.0 beta release we’ve disabled the automatic ganache instance feature to keep working on its stability, so you’ll need to run it manually. This feature will be back by the time we ship the stable release. Please run ganache-cli in a separate terminal to keep going.

To run it, try npx buidler accounts:

$ npx buidler accounts
Accounts: [ '0x9d6bd5939d6e2629f2bdffac5417ba22e31ea6a5',
  '0x23024feafd6587ef4576496484fee2796ba66e3c' ]

You will learn how to create your own tasks in the next guide.

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

pragma solidity ^0.5.1;

contract Greeter {

    string greeting;

    constructor(string memory _greeting) public {
        greeting = _greeting;

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


To compile it, simply run:

npx buidler compile

Now, you’ll likely want to run some tests. Let’s install buidler-truffle5 and test out the Truffle integration:

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

Add usePlugin("@nomiclabs/buidler-truffle5") to the top of your buidler.config.js, so that it looks like this:


task("accounts", "Prints a list of the available accounts", async () => {
  const accounts = await ethereum.send("eth_accounts");

  console.log("Accounts:", accounts);

module.exports = {};

Change test/sample-test.js to:

const assert = require("assert");

describe("Ethereum provider", function() {
  it("Should return the accounts", async function() {
    const accounts = await ethereum.send("eth_accounts");
    assert(accounts.length !== 0, "No account was returned");

contract("Greeter", function() {
  it("Should give the correct greeting", async function() {
    const Greeter = artifacts.require("Greeter");
    const greeter = await"Hello, Buidler!");

    assert.equal(await greeter.greet(), "Hello, Buidler!");

And run npx buidler test

$ npx buidler test
Compiled 1 contract successfully

  Ethereum provider
    ✓ Should return the accounts

    ✓ Should give the correct greeting (376ms)

  2 passing (383ms)

Next, to deploy the contract we will use the Truffle plugin again. Create a file deploy.js in scripts/:

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

  const greeter = await"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.

These cover the basics to start using Buidler. Move on to the next section to learn more.

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

Last Updated: 9/13/2019, 8:38:59 PM