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. By default, 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 override this behavior with the NETLIFY_USE_YARN variable described in the section on Yarn.

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. You can override this behavior with the NETLIFY_USE_YARN environment variable described below.

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

  • NETLIFY_USE_YARN: undefined by default. If true, Netlify will install and run Yarn. If false, we will use npm. If left unset, we will run Yarn if and only if the site's base directory includes a yarn.lock file.
  • 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.

Yarn is not the default

If any of your build scripts start with yarn, you must either have a yarn.lock file in your site's base directory or set NETLIFY_USE_YARN to true. Netlify's buildbot will not install Yarn without it.

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

Python

The default Python version is determined by the site's selected build image.

You can choose the Python version we use to build your site in one of the following ways:

  • Set a PYTHON_VERSION environment variable.
  • Add a runtime.txt file to the site's base directory in your repository. The file must include the version number only: x.y, with no trailing newline.
  • Use Pipenv to specify a version and save it to a Pipfile in the site's base directory in your repository.

runtime.txt overrides Pipfile

If the site's base directory includes both a runtime.txt file and a Pipfile, Netlify will use the version specified in runtime.txt.

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

Python dependencies

If your build requires any Python dependencies, you must provide a list of these for installation using pip or Pipenv.

Install via pip

If you manage your Python dependencies using pip, you can generate a list of them by running the following command in the site's base directory in your repository:

pip freeze > requirements.txt

This creates a requirements.txt file that Netlify will use to install your dependencies via pip install. Refer to the pip docs for more details about the requirements file format.

Install via Pipenv

If you manage your Python dependencies using Pipenv, be sure to commit your Pipfile to the site's base directory in your repository. Netlify will run pipenv install to install your dependencies. If you also commit your Pipfile.lock, this will ensure that pipenv install installs the same exact versions of your dependencies on Netlify as it does locally.

requirements.txt overrides Pipfile

If the site's base directory includes both a runtime.txt file and a Pipfile, Netlify will run pip install to install the dependencies in requirements.txt, and ignore the dependencies in the Pipfile.

Swift

A default Swift version does not come preinstalled on a site's selected build image. Instead, at the time of the first build, Netlify installs your specified Swift version in the build container.

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

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

Both methods above will accept any Swift version that swiftenv can install that is later than Swift 4.x. Versions 4.x and earlier aren't supported due to incompatible shared libraries. We recommend specifying a version of Swift that matches your local development environment.

Default Swift version

If no SWIFT_VERSION environment variable is set and no .swift-version file is present but a Package.swift file exists in the site's base directory in the repository, Netlify installs a default Swift version determined by the site's selected build image.

Your selected version will be initially installed using swiftenv and then cached to speed up subsequent builds.

Swift dependencies

If your build requires any Swift dependencies, you must list these in a Package.swift manifest file saved in the site's base directory in your repository. During the build, our buildbot runs the swift build command, using Swift Package Manager to install the dependencies and exact versions specified in Package.swift. For more information about managing dependencies with the manifest file, visit the Swift Package Manager documentation.

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.