Build Settings

Our build environment is quite flexible about what you can do — but there are some things we do automatically. For a full breakdown of “how it works”, see this blog post:

This build pipeline is used ONLY if you deploy from Git rather than via API, CLI, or drag and drop methods.

When it comes to setting up your build pipeline on Netlify, the hope is that it will take minimal to no effort to build the site the same way you already do. The most common configuration is intended not to be “change your build pipeline” but instead “choose the appropriate version of the tools we’ll use automatically for you, so they work the same as they do in your local environment”. This document describes the variables that can affect what version of Ruby, Node, NPM, YARN, Python, and Hugo we use. All of the installing of dependencies described here happens before your build command is run — so you can include webpack in your /package.json and be confident that it will be npm install‘ed before we run your build command webpack!

In addition to the below variables you can set, we automatically set some variables you can key off of in your builds. These are listed in this documentation . To configure additional build variables, you can do it either per-site in your site settings (Settings > Build & Deploy > Continuous Deployment > Build Environment Variables) or via netlify.toml. netlify.toml is parsed per-build and allows you to set per-build, per-branch, or per-deploy-type settings — as well as global settings.

Build Environment Variables

Node, NPM, and Yarn

  • NODE_ENV is by default set to development (typical settings: production or development; setting globally allows all dependency installations to work with our caching.)
  • NODE_VERSION is by default pinned to version that we had systemwide when you created your site. Best practice is to set explicitly via a /.nvmrc file or a NODE_VERSION environment variable. Versions possible: any released version.
  • If you have a /yarn.lock file: you can set YARN_VERSION (any released version), YARN_FLAGS (flags to pass to our automatic yarn install that runs when this file is present). YARN_FLAGS is set to --ignore-optional by default. /package.json file is ignored in regards to the next step below if you have a /yarn.lock!
  • If instead you have a /package.json file: you can set NPM_VERSION (any released version), NPM_FLAGS (flags to pass to our automatic npm install that runs when this file is present AND there is no /yarn.lock). Default NPM_VERSION is not needed — we’ll use the version that shipped with the version of Node.js being used.
  • If you use NPM, then you can set an NPM_TOKEN environment variable which we can be configured to use to fetch dependencies from For more details about how to configure things, this gist describes the workflow.


  • /Gemfile and /Gemfile.lock are required to list dependencies (e.g. “jekyll” or “middleman”) which your build needs. You can use bundle install to create Gemfile.lock from a Gemfile, whose contents must follow this specification.
  • Set Ruby version via a /.ruby-version file. You must choose from among rvm’s supported versions. Note that the syntax for this file is JUST the version number: x.y.z, with no trailing newline. The following versions are already installed and will create the fastest builds.
    • 2.2.9
    • 2.3.6
    • 2.4.3


  • /requirements.txt will have pip install automagically run against it. It must follow this specification.

  • /runtime.txt may list a python version to use from the list of pre-installed pythons (see this file in our build-image repository for the up-to-date list). Note that the syntax for this file is JUST the version number: x.y, with no trailing newline. The supported versions include:

    • 2.7
    • 3.4
    • 3.5
    • 3.6


  • By default we’ll use the Hugo version that we had set as default when you created your site. For almost everyone, that is “version 0.17”.
  • You can change this in two ways:
    • a HUGO_VERSION environment variable can be set to the version string for any released version after 0.19, and if you set this, you can set your build command to simply hugo. Please read this blog post for more details about how we handle this.
  • If you want to use an older versions you can instead run different build commands: hugo_0.13, hugo_0.14, hugo_0.15, hugo_0.16, hugo_0.17, hugo_0.18, or hugo_0.19


  • If there is a /bower.json file we’ll automatically run bower install --config.interactive=false against it to install your bower dependencies. This is IN ADDITION TO running npm install or yarn install as described above


  • We automatically provide grunt for you in the build environment in case your build command references it. We’ll run npm install grunt-cli for you before running your build command, in case your build command contains the string grunt

Additional variables that can affect the build:

  • If you set a GIT_LFS_ENABLED variable, we’ll use git lfs clone to check out your repository — otherwise we just use git clone.

Notice something is incorrect or outdated?

First off, great eye! We appreciate your discovery and want to ensure it gets addressed immediately. Please let us know here.

Want to get started quick?