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:
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
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 our documentation on environment variables. You can configure additional build variables at the team level in the UI (Team settings > Sites > Global site settings > Shared environment variables), at the site level in the UI (Settings > Build & deploy > Environment > Environment variables), or via
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_ENVis by default set to
development(typical settings: production or development; setting globally allows all dependency installations to work with our caching.)
NODE_VERSIONis initially set to the default version in your site’s build image. Best practice is to set explicitly via a
/.nvmrcfile or a
NODE_VERSIONenvironment 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.lockfile: you can set
YARN_VERSION(any released version),
YARN_FLAGS(flags to pass to our automatic
yarn installthat runs when this file is present).
YARN_FLAGSis set to
/package.jsonfile is ignored in regards to the next step below if you have a
- If instead you have a
/package.jsonfile: you can set
NPM_VERSION(any released version),
NPM_FLAGS(flags to pass to our automatic
npm installthat runs when this file is present AND there is no
NPM_VERSIONis 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_TOKENenvironment variable which can be configured to use to fetch dependencies from npmjs.org. For more details about how to configure things, this gist describes the workflow.
/Gemfile.lockare required to list dependencies (e.g. “jekyll” or “middleman”) which your build needs. You can use
bundle installto create
Gemfile.lockfrom a Gemfile, whose contents must follow this specification.
- Set Ruby version via a
/.ruby-versionfile. 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.
pip installautomagically run against it. It must follow this specification.
/runtime.txtmay 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.
- 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:
HUGO_VERSIONenvironment 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:
- If there is a
/bower.jsonfile we’ll automatically run
bower install --config.interactive=falseagainst it to install your bower dependencies. This is IN ADDITION TO running
yarn installas 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-clifor you before running your build command, in case your build command contains the string
Additional variables that can affect the build:
- If you set a
GIT_LFS_ENABLEDvariable, we’ll use
git lfs cloneto check out your repository — otherwise we just use
Build image selection
This feature is in
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 catch! We appreciate your discovery and want to ensure it gets addressed immediately. Please let us know here.
Want to have a conversation?
Visit the Netlify Community to discuss ideas and questions with your fellow Netlify users.