Manage build dependencies

When you trigger a build on Netlify, our build system starts a Docker container to build your site. Before running your build command, the build system will search 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 the following ways:

• Navigate to Project configuration > Build & deploy > Continuous deployment > Dependency management in the Netlify UI and select from the major Node.js versions that Netlify currently supports. Once you change the version, you need to redeploy your site for it to take effect. Note that a NODE_VERSION environment variable, .node-version file, or .nvmrc file will override this UI setting.
• Set a NODE_VERSION environment variable with any released version of Node.js or any valid string that nvm understands. You can either set a specific version or set a major version, such as the number 22 for the latest version of Node.js 22.x.
• Add a .node-version or .nvmrc file to the site’s base directory in your repository. The file can include any released version of Node.js or any valid string that nvm understands. You can either set a specific version or set a major version, such as the number 22 for the latest version of Node.js 22.x.

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

If you are using the Netlify CLI to run a build locally, make sure the Node.js version installed in your local environment matches the version set for your build on Netlify. If the versions don’t match, you may encounter errors.

What about the Node.js version for functions?

Typically, the functions runtime Node.js version automatically matches the version used for the build. If you need to customize the Node.js version for your functions, use the AWS_LAMBDA_JS_RUNTIME environment variable. Visit our docs on Node.js version for runtime to learn more.

Node.js environment

By default, Netlify’s build system 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 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, 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 repository does not include a yarn.lock, pnpm-lock.yaml or bun.lockb file, we will run npm install to install the dependencies listed in your package.json.

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

• NPM_VERSION: variable that defaults to the version preinstalled with your version of Node.js. Accepts any released version number.
• NPM_FLAGS: used to indicate the flags to pass to the npm install command. For example, you could pass the --global flag to make installed packages available outside your working directory. Learn more about npm flags in the npm docs.
• NPM_TOKEN: used for authentication when installing private npm modules. Visit our Forums for a verified Support Guide on configuration details when using private npm modules on Netlify.

pnpm

Netlify supports pnpm for Node.js 16.9.0 and later.

If your site’s base directory includes a pnpm-lock.yaml file, we will run pnpm install to install the dependencies listed in your package.json.

To specify a pnpm version, you can edit your package.json file:

"packageManager": "pnpm@6.3.2"

This tells Corepack to use and download your preferred pnpm version instead of the default version that Netlify sets.

Note that based on Corepack limitations, you cannot use semver to specify a range of versions for this package manager.

In certain scenarios, you must pass additional flags to the pnpm install command. For example, some frameworks such as Nuxt 3 and Next.js require that you modify the pnpm install command. To avoid import issues with pnpm and these frameworks, use the PNPM_FLAGS environment variable and set it to --shamefully-hoist.

Yarn

Netlify can detect and install Yarn and then use it to install your project’s dependencies. If you commit a yarn.lock file to your site’s repository or if your packageManager property specifies Yarn, Netlify will install Yarn and then run the yarn command to install the dependencies specified in your yarn.lock file.

By default, Netlify will use the Yarn version preinstalled with your initial build image.

Note that based on Corepack limitations, you cannot use semver to specify a range of versions for this package manager.

To specify a different Yarn version:

• You can edit your package.json file:

    "packageManager": "yarn@3.2.4"

• Or, you can leverage Yarn’s way of vendoring a specific version by setting a yarnPath inside a .yarnrc.yml file.

  yarnPath: .yarn/releases/yarn-3.2.4.cjs
  nodeLinker: node-modules

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

• YARN_FLAGS: used to indicate the 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_NPM_AUTH_TOKEN: used for authentication when installing private npm modules.
• NETLIFY_USE_YARN: deprecated variable that is supported but no longer recommended; undefined by default. If true, Netlify will install and run Yarn. If false, we will use npm or pnpm. If left unset, we will run Yarn if the site’s package.json specifies yarn as the package manager or if a yarn.lock file is present.
• YARN_VERSION: deprecated variable that is supported but no longer recommended; defaults to the version preinstalled with your initial build image. Accepts any released version number. We recommend setting the version in package.json or through a yarnPath in .yarnrmc.yml instead.

Yarn Berry requires a setting in .yarnrc.yml

To build your project on Netlify with Yarn 2.0.0 or later, you must add nodeLinker: node-modules to a .yarnrc.yml file, which is generally stored in your repository root. Netlify depends on the node_modules folder tree that’s generated with this setting. Plug’n’Play is not currently supported on Netlify.

Bun

Netlify can detect when your project is using Bun and then use it to install your project’s dependencies. If you commit a bun.lockb file to your site’s repository, Netlify will run the bun install command to install the dependencies specified in your bun.lockb file.

All builds will use the version pre-installed in our build image.

You can also customize your Bun use with the following environment variables:

• BUN_FLAGS: used to indicate the flags to pass to the bun install command.
• BUN_VERSION: to set the version of Bun we use for the build. You can use any released version of Bun.

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.

Go

A build’s initial Go version is determined by the default version for the site’s build image. You can change the Go version we use to build your site in the following ways:

• Set a GO_VERSION environment variable with any released version of Go. You can also use a partial version, such as 1.20, to indicate the latest version of 1.20.
• Add a .go-version file to the site’s base directory in your repository. The file can include any released version of Go.

.go-version overrides GO_VERSION

Note that if your site has both a .go-version file and a GO_VERSION environment variable, the .go-version file takes precedence.

We recommend matching your local development environment’s Go version to your selected build image’s Go version. You can use any version of Go that’s available on the Go downloads page.

The configured Go version is also used when compiling Go serverless functions during the build.

PHP

You can choose the PHP version we use to build your site by setting a PHP_VERSION environment variable. We recommend matching your local development environment’s PHP version to a version that your selected build image supports. For a list of supported versions, refer to the available software at build time doc.

PHP dependencies

Add your PHP dependencies to a composer.json file. Dependencies listed in composer.json are automatically installed with Composer, which is included in all build images.

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 using 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 by running pip install. Refer to the pip docs for more details about the requirements file format.

Install using 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 requirements.txt file and a Pipfile, Netlify will run pip install to install the dependencies in requirements.txt, and ignore the dependencies in the Pipfile.

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.

Rust

Although rustup and cargo are preinstalled, Netlify doesn’t install a default Rust toolchain.

You must specify the Rust toolchain used to build your site in one of the following ways:

• Add a rust-toolchain file to the site’s base directory in your repository. This is the recommended option. When a rust-toolchain file is present, cargo installs the toolchain when it first executes, for example, on cargo build.
• Include a toolchain install command as part of your site’s build command. Use the syntax rustup toolchain install <toolchain>, for example: rustup toolchain install stable.

The build image supports any toolchain that rustup can install. The selected Rust toolchain is cached to speed up subsequent builds. Crates are cached in ~/.cargo/registry, and compilation assets are cached in target if your working directory has a Cargo.toml or Cargo.lock file.

Rust dependencies

Include any Rust dependencies in a Cargo.toml manifest file in the base directory in your repository. If you also commit a Cargo.lock, this will ensure that cargo installs the same exact versions of your Rust dependencies on Netlify’s build image as it does locally. Dependencies aren’t installed automatically. Instead cargo fetches them when cargo doc or cargo build executes as part of the build command.

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

Build image defaults

Netlify’s build images have default preinstalled versions for many languages and tools. For a full list of defaults and more information on how to manage versions, refer to our available software at build time doc.

Not sure what build image your project uses? You can find out in the Netlify UI, by navigating to Project configuration > Build & deploy > Continuous deployment > Build image selection. You can also find all of the software versions your build uses in your site’s deploy logs.

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

If you change your dependency requirements, 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 searching 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 check if this works better. You can do this by deploying the latest branch commit with the clear cache option.