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.
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
- Add a
.nvmrcfile 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.
By default, Netlify's buildbot sets
development. You can change this value by setting a
NODE_ENV environment variable.
Dependencies and production
If you set the
devDependencies in your
package.json file will not be installed for the build.
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.
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 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
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_TOKEN: use for authentication when installing private npm modules. Visit our Community forum for configuration details when using private npm modules on Netlify.
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 needs a
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
--ignore-optionalby default. You can override this by adding
--no-ignore-optionalto this variable.
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.
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
- Add a
.ruby-versionfile 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 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.
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
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 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.
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
pip install to install the dependencies in
requirements.txt. Refer to the pip docs for more details about the requirements file format.
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.
Did you find this doc useful?
Your feedback helps us improve our docs.