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:

https://www.netlify.com/blog/2016/10/18/how-our-build-bots-build-sites

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 initially set to the default version in your site’s build image. Best practice is to set explicitly via a /.nvmrc file or a NODE_VERSION environment variable. You can choose any released version, but for faster builds, we recommend choosing a version that is preinstalled on your site’s selected build image.
  • 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 npmjs.org. For more details about how to configure things, this gist describes the workflow.

Ruby

  • /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. For faster builds, you can choose one of the Ruby versions preinstalled in your site’s selected build image. Note that the syntax for this file is JUST the version number: x.y.z, with no trailing newline.

Python

  • /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 versions preinstalled in your site’s selected build image. Note that the syntax for this file is JUST the version number: x.y, with no trailing newline.

Hugo

  • By default we’ll use the Hugo version that is preinstalled in your site’s initial build image.
  • 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

Bower

  • 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

Grunt

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

Build image selection

This feature is in beta.

When a build is triggered on Netlify, our buildbot starts a Docker container running a build image. The build image is a snapshot of an operating system that is preinstalled with various software tools and other settings.

Until recently, all Netlify sites were built using the same build image. We are now experimenting with allowing customers to select from multiple images with different operating system and software versions.

You might choose a different build image to meet a software requirement for your build tool, to try out experimental build features before we release them, or to just keep up to date with the included operating system environment. This will also allow us to release breaking changes into our build image and allow users to accommodate those changes when they have time to upgrade.

All Netlify build images are stored in a public GitHub repository. The repository README includes a list of available images and instructions for testing locally.

To change the build image for a site, go to the site Settings > Build & deploy > Continuous Deployment > Build image selection, and select the build image you would like to use. This image will be used for all production deploys, as well as branch deploys and deploy previews.


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?