Node.js Versioning in Nixpacks

Nixpacks only supports major version specification for Node.js. This page explains the limitation and provides a workaround for pinning specific minor or patch versions.

Understanding the Limitation

According to the Nixpacks Node provider documentation:

"Only a major version can be specified. For example, 18.x or 20."

When you specify a Node.js version via:

• NIXPACKS_NODE_VERSION environment variable
• engines.node in package.json
• .nvmrc or .node-version files

You can only control the major version (e.g., 20, 22). The specific minor and patch version (e.g., 22.13.1 vs 22.14.0) is determined by the nixpkgs archive that Nixpacks uses internally.

The Problem

You set "node": ">=22" in your package.json or NIXPACKS_NODE_VERSION=22, but your application needs Node 22.14.0 specifically. Nixpacks may instead provide 22.12.0 or another patch version from its default nixpkgs archive—causing runtime issues if your code depends on features from a newer patch.

Workaround

To pin a specific minor/patch version, you can override the nixpkgs archive in your nixpacks.toml file. Create this file in your repository root:

[phases.setup]
nixpkgsArchive = '51ad838b03a05b1de6f9f2a0fffecee64a9788ee'

The nixpkgsArchive value is a commit SHA from the NixOS/nixpkgs repository. Each commit contains specific package versions, so by pinning a commit, you control the exact versions available.

Finding the Right Archive Commit

To find a nixpkgs commit containing your required Node.js version:

1. Browse the NixOS/nixpkgs repository
2. Search for files like v20.nix, v22.nix, or v24.nix (the Node.js version definition files)
3. Check the commit history for when your desired version was added
4. Copy the full commit SHA

Some verified commits for Node.js:

• 51ad838b03a05b1de6f9f2a0fffecee64a9788ee → Node 22.13.1
• bf744fe90419885eefced41b3e5ae442d732712d → Node 22.x versions
• ffeebf0acf3ae8b29f8c7049cd911b9636efd7e7 → Node 22.14.0 (unstable branch)

Learn more in the Nixpacks docs on nixpkgs archive.

Node.js Version Reference (SHA256 Hashes)

The following tables list Node.js versions and their SHA256 hashes from the nixpkgs history. These can help you verify you're getting the expected version when working with nixpkgs archives.