Build image

Workers Builds uses a build image with support for a variety of languages and tools such as Node.js, Python, PHP, Ruby, and Go.

Workers Builds supports a variety of runtimes, languages, and tools. Builds will use the default versions listed below unless a custom version is detected or specified. You can override the default versions using environment variables or version files. All versions are available for override.

The build image preinstalls Node.js 22.23.4 and 24.22.1.

For details on the packageManager field, refer to Package manager versions.

If you need to override a specific version of a language or tool within the image, you can specify it as a build environment variable, or set the relevant file in your source code as shown above.

To set the version using a build environment variables, you can:

1. Find the environment variable name for the language or tool and desired version (e.g. NODE_VERSION = 22)
2. Add and save the environment variable on the dashboard by going to Settings > Build > Build Variables and Secrets in your Workers project

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

1. Find the filename for the language or tool (e.g. .nvmrc)
2. Add the specified file name to the root directory and set the desired version number as the file's content. For example, if the version number is 22, the file should contain '22'.

To set the version of npm, yarn, pnpm, or Bun, add the packageManager ↗︎ field to your package.json. This is the only way to change the npm version.

{
	"packageManager": "npm@11.19.1"
}

• Workers Builds reads packageManager from the package.json in your project's root directory. If the root directory is not the top level of your repository, Workers Builds also reads the package.json at the top level of the repository. If both files set packageManager, use the same value in each.
• Use an exact version, such as npm@11.19.1. Do not use ranges such as npm@^11.
• The engines.npm field in package.json does not set the npm version. If you only set engines.npm, Workers Builds uses the default npm version, and npm prints an EBADENGINE warning instead of failing.
• packageManager sets the version of the package manager. The lockfile in your repository still determines which package manager installs your dependencies.

Workers Builds runs pnpm through Corepack ↗︎. With the default Corepack settings, version selection follows this order:

1. The top-level packageManager field in package.json.
2. devEngines.packageManager in package.json, when it specifies pnpm and a version.
3. The PNPM_VERSION build variable.
4. The build image's default pnpm version.

Project version requirements take precedence over PNPM_VERSION. Use an exact version to keep builds consistent. A version range in devEngines.packageManager can select different releases across builds. The pnpm version recorded in pnpm-lock.yaml does not pin the version Corepack runs.

The Detected the following tools from environment log line reports tool selection before Corepack applies devEngines.packageManager. Check pnpm's install output for the version that actually ran.

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

In the following table, review the pre-installed packages in the build image. The packages are installed with apt, a package manager for Linux distributions.

Workers Builds are run in the following environment:

Build commands use the CA certificates installed in the build image at /etc/ssl/certs/ca-certificates.crt. Workers Builds sets the following environment variables so that runtimes with their own bundled CA certificates use them as well, including older versions you select with a version override:

If you set any of these variables as a build variable, your value replaces the default. --use-openssl-ca is added to your own NODE_OPTIONS, unless it already contains --use-openssl-ca or --use-bundled-ca.

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
• Pin specific versions of critical preinstalled software by overriding default versions