Build image

Cloudflare Pages' build environment has broad support for a variety of languages, such as Ruby, Node.js, Python, PHP, and Go.

If you need to use a specific version of a language, (for example, Node.js or Ruby) you can specify it by providing an associated environment variable in your build configuration, or setting the relevant file in your source code.

In the following tables, review the preinstalled versions for languages and tools included in the Cloudflare Pages' build image, and the environment variables and/or files available for overriding the preinstalled version:

To use a specific version of a framework, specify it in the project's package manager configuration file. For example, if you use Gatsby, your package.json should include the following:

"dependencies": {
	"gatsby": "^5.13.7",
}

When your build starts, if not already cached, version 5.13.7 of Gatsby will be installed using npm install.

To override default versions of languages and tools in the build system, you can either set the desired version through environment variables or by adding files to your project.

To set the version using environment variables, you can:

1. Find the environment variable name for the language or tool in this table.
2. Add the environment variable on the dashboard by going to Settings > Environment variables in your Pages project, or add the environment variable via Wrangler.

Or, to set the version by adding a file to your project, you can:

1. Find the file name for the language or tool in this table.
2. Add the specified file name to the root directory of your project, and add the desired version number as the contents of the file.

For example, if you were previously relying on the default version of Node.js in the v1 build system, to migrate to v2, you must specify that you need Node.js 12.18.0 by setting a NODE_VERSION = 12.18.0 environment variable or by adding a .node-version or .nvmrc file to your project with 12.18.0 added as the contents to the file.

You can add the following environment variable to disable automatic dependency installation, and run a custom install command instead.

The v3 build system updates the default tools, libraries and languages to their LTS versions, as of May 2025.

To migrate to this new version, configure your Pages project settings in the dashboard:

1. In the Cloudflare dashboard, go to the Workers & Pages page.

   Go to Workers & Pages ↗

2. Select your Pages project.

3. Go to Deployments > All deployments > and select the latest version.

If you were previously relying on the default versions of any languages or tools in the build system, your build may fail when migrating to v3. To fix this, you must specify the version you wish to use by overriding the default versions.

The following features are not currently supported when using the v3 build system:

• Specifying Node.js versions as codenames (for example, hydrogen or lts/hydrogen).
• Detecting Yarn version from yarn.lock file version.
• Detecting pnpm version detection based pnpm-lock.yaml file version.
• Detecting Node.js and package managers from package.json -> "engines".
• pipenv and Pipfile support.

Cloudflare Pages builds are run in a gVisor ↗ container.

If you are currently using the v1 or v2 build image, your project will be automatically moved to v3:

• v1 build image: If you are using the Pages v1 build image, your project will be automatically moved to v3 on September 15, 2026.
• v2 build image: If you are using the Pages v2 build image, your project will be automatically moved to v3 on February 23, 2027.

You will receive 6 months’ notice before the deprecation date via the Cloudflare Changelog ↗, dashboard notifications, and email.

Going forward, the v3 build image will receive rolling updates to preinstalled software per the policy below. There will be no further build image version changes.

Preinstalled software (languages and tools) will be updated before reaching end-of-life (EOL). These updates apply only if you have not overridden the default version.

• Minor version updates: May be updated to the latest available minor version without notice. For tools that do not follow semantic versioning (e.g., Bun or Hugo), updates that may contain breaking changes will receive 3 months’ notice.
• Major version updates: Updated to the next stable long-term support (LTS) version with 3 months’ notice.

How you'll be notified (for changes requiring notice):

• Cloudflare Changelog ↗
• Dashboard notifications for projects that will receive the update
• Email notifications to project owners

To maintain a specific version and avoid automatic updates, override the default version.

To avoid unexpected build failures:

• Monitor announcements via the Cloudflare Changelog ↗, dashboard notifications, and email
• Plan for migration when you receive update notices
• Pin specific versions of critical preinstalled software by overriding default versions