Netlify Node version pinning: netlify.toml NODE_VERSION vs .nvmrc – which source wins?

Direct answer

When both a NODE_VERSION variable defined in netlify.toml (under [build.environment]) and a .nvmrc or .node-version file exist in the repository, Netlify uses the value from netlify.toml and ignores the file‑based version.

Confirmed facts

• Netlify first checks for build‑time environment variables, including those set in the Site UI → Build & deploy → Environment and those declared in netlify.toml under [build.environment].
• If no NODE_VERSION is found via those environment variables, Netlify falls back to reading a version from .nvmrc or .node-version in the repository root.
• The selected build image (Ubuntu Focal, Jammy, etc.) only supplies a default Node version when neither source specifies a version; it does not alter the precedence order.

Likely explanation

Variables placed in netlify.toml are injected into the build environment as ordinary environment variables. Because environment variables have higher precedence than file‑based version files in Netlify’s resolution logic, the NODE_VERSION from netlify.toml wins over .nvmrc. UI‑defined environment variables outrank both, as they are applied after the repository is cloned.

Steps to ensure consistent Node version

1. Decide where you want to manage the version (recommended: netlify.toml for centralized control).
2. Set NODE_VERSION under [build.environment] in netlify.toml to the exact version you use locally.
3. Keep a matching .nvmrc (or .node-version) for local developer convenience, but verify it matches the value in netlify.toml.
4. Check the Netlify Site UI for any existing NODE_VERSION environment variable; if present, it will override both the file and the netlify.toml setting.
5. Push a commit, trigger a build, and inspect the build logs for the line indicating the Node version used (e.g., "Node version: 18.12.0").

If you are unsure whether a UI environment variable is set, please confirm that detail, as it would change the recommendation (the UI variable would take precedence).