Manage build dependencies

When you trigger a build on Netlify, our buildbot starts a Docker container to build your site. Before running your build command, the buildbot will look for instructions about required languages and software needed to run your command. These are called dependencies, and how you declare them depends on the languages and tools used in your build.

Follow the guidelines below to specify your required dependencies, and Netlify will install them before running your build. Any executables from these dependencies will be made available from the PATH for the remainder of the build.

Node.js and JavaScript

A build's Node.js version is initially determined by the default version preinstalled on the site's selected build image. We pin the site to that version so your builds won't change even if the build image's defaults change.

You can choose the Node.js version we use to build your site in two different ways:

  • Set a NODE_VERSION environment variable.
  • Add a .node-version or .nvmrc file to the site's base directory in your repository. This will also tell any other developer using the repository which version of Node.js it depends on.

Both methods above will accept any released version of Node.js, or any valid string that nvm understands. You can either set a specific version or just have a major version, such as the number 10 for the latest version of Node.js 10.x.

The version of Node.js you use is dynamically fetched using nvm and then cached to speed up subsequent builds.

Node.js environment

By default, Netlify's buildbot sets NODE_ENV to development. You can change this value by setting a NODE_ENV environment variable.

Dependencies and production

If you set the NODE_ENV to production, any devDependencies in your package.json file will not be installed for the build.

JavaScript dependencies

If your build requires any JavaScript dependencies, you must list these in a package.json file saved in the site's base directory in your repository. You can visit the npm docs to learn how to create a package.json file.

Tip

If you're having trouble linking to other repositories in your package.json file, visit the repository permissions and linking doc for more information.

npm

npm comes preinstalled with Node.js, so any build scripts using npm run will work automatically. If your site's base directory does not include a yarn.lock file (more information below), we will run npm install to install the dependencies listed in your package.json file.

You can customize your npm use with the following environment variables:

  • NPM_VERSION: defaults to the version preinstalled with your version of Node.js. Accepts any released version number.
  • NPM_FLAGS: flags to pass to the npm install command.
  • NPM_TOKEN: use for authentication when installing private npm modules. Visit our Community forum for configuration details when using private npm modules on Netlify.

Yarn

If you use Yarn locally to install the JavaScript dependencies in your package.json file, Yarn will create a yarn.lock file to record the module names and versions installed. If you commit this file to the site's base directory in your repository, we will install Yarn and run the yarn command to install the dependencies specified in your yarn.lock file.

yarn needs a yarn.lock

If any of your build scripts start with yarn, you must have a yarn.lock file. Netlify's buildbot will not install Yarn without it.

You can customize your Yarn use with the following environment variables:

  • YARN_VERSION: defaults to the version preinstalled with your initial build image. Accepts any released version number.
  • YARN_FLAGS: flags to pass to the yarn command. Includes --ignore-optional by default. You can override this by adding --no-ignore-optional to this variable.

Bower

If your repository includes a bower.json file in the base directory, we’ll automatically run bower install --config.interactive=false against it to install your Bower dependencies. This is in addition to running any other requisite dependency management commands as described in this doc.

Ruby

A build's Ruby version is initially determined by the default version preinstalled on the site's selected build image. We pin the site to that version so your builds won't change even if the build image's defaults change.

You can choose the Ruby version we use to build your site in two different ways:

  • Set a RUBY_VERSION environment variable.
  • Add a .ruby-version file to the site's base directory in your repository. This will also tell any other developer using the repository which version of Ruby it depends on.

No newlines in .ruby-version

The .ruby-version file must include the version number only: x.y.z, with no trailing newline.

Both methods above will accept any released version of Ruby, or any valid string that RVM understands. We recommend specifying a version of Ruby that matches your local development environment.

If the version you select is preinstalled in your site's selected build image, it will be available immediately. If not, your selected version will be installed using rvm and then cached to speed up subsequent builds.

Ruby dependencies

If your build requires any Ruby dependencies, you must list these in a Gemfile saved in the site's base directory in your repository. We use Bundler to install the dependencies in that file. You can visit the Bundler docs to learn how to manage Ruby dependencies with Bundler.

If you run the bundle install command locally, Bundler will create a Gemfile.lock file to record the gem names and versions installed. If you commit this file to the site's base directory in your repository, we will install the exact versions specified in your Gemfile.lock file.

Python

The default Python version is determined by your site's selected build image. You can choose a different version by specifying it in a runtime.txt file in the site's base directory in your repository.

No newlines in runtime.txt

The runtime.txt file must include the version number only: x.y, with no trailing newline.

The list of supported versions depends on your site's selected build image.

Python dependencies

If your build requires any Python dependencies, you must list these in a requirements.txt file saved in the site's base directory in your repository. You can create this file by running the following command in the base directory:

pip freeze > requirements.txt

Netlify runs pip install to install the dependencies in requirements.txt. Refer to the pip docs for more details about the requirements file format.

Dependency cache

The first build you do can take some time while we install all of your dependencies. After the initial build, we'll cache the dependencies so we don't have to install them every time you push an update. This is intended to make subsequent builds really fast.

If you change your dependency requirements by changing one of the files or settings above, the next build will re-run the installation command which may update cached dependencies if needed. It isn’t guaranteed a change will take place if the previous dependencies still satisfy the installer, though! You can check which directories are cached by looking for $NETLIFY_CACHE_DIR in the run-build-functions.sh file for your site's selected build image.

If a build fails, it's worth retrying with a cleared build cache to see if this works better. You can do this by selecting the Retry deploy button in the header of a failed deploy log page, and then selecting Clear cache and deploy site.