Node.js how-to
How to Check Node Version (and Switch or Pin It)
Most Node.js problems that look mysterious come from the wrong runtime version: the laptop runs one major, the container runs another, and CI runs a third. This guide shows how to check the version in use, how to read the release numbers, and how to switch and pin a version so every environment runs the same one.
By Jasdeep Bains, SeaGit
·
Key takeaways
- Run node -v to see the version the shell uses. The number that matters is the major, such as 22 or 24.
- Even-numbered majors become LTS. Odd-numbered majors are Current only and never reach LTS.
- Pin one major per project with a .nvmrc file, an engines field, and the same major in your Dockerfile and CI.
- If the version changes after you install something, the cause is almost always PATH order or a shell that did not load your version manager.
Check the Node.js and npm version
Open a terminal and run the command below. Both spellings return the same answer, so use whichever you remember.
node -v # same as: node --version
npm -v # npm ships with Node but has its own version number
node -p process.versions.node # the full version, e.g. 24.1.0
node -p process.versions.v8 # the bundled V8 engine versionInside application code, read the same value from the runtime. This is useful for a startup log line or a health endpoint that reports which runtime is serving traffic.
console.log(process.version); // "v24.1.0"
console.log(process.versions.node); // "24.1.0"
console.log(process.versions.v8); // V8 engine versionWhat the version numbers mean
A Node.js version has three parts: major, minor and patch. 24.1.0 is major 24, minor 1, patch 0. Compatibility decisions, such as which packages install and which language features exist, depend on the major. Minor and patch releases are meant to be safe within a major.
Each major moves through release phases. Current receives most non-breaking changes. Active LTS gets features and fixes that the release team has judged stable. Maintenance gets only critical fixes and security updates. The release team sets these dates in the nodejs/release schedule.
Release lines and what to choose
| Phase | What it means for you |
|---|---|
| Current | Newest features. Good for trying things, usually not the line to run in production. |
| Active LTS | The default choice for a new production service. |
| Maintenance | Security and critical fixes only. Plan a move to a newer LTS before end-of-life. |
Even-numbered majors enter LTS, and odd-numbered majors do not. As of October 2026, the schedule lists 24.x as Active LTS, 22.x as Maintenance and 26.x as Current. Check the live table at github.com/nodejs/release before you commit to a line, because the dates can change.
Switch between Node versions
A version manager installs several majors side by side and points node at one of them. Pick one tool and use it everywhere. nvm is the most common on macOS and Linux.
# nvm (macOS, Linux, WSL)
nvm install --lts # install the current Active LTS
nvm install 24 # install the latest 24.x
nvm use 24 # switch this shell to 24.x
nvm ls # list installed versions
nvm alias default 24 # new shells start on 24.x
nvm current # print the version in useOther tools
- nvm-windows is a separate project from nvm. It does not read .nvmrc automatically, so run nvm use 24.1.0 with the exact version. Use nvm list to see what is installed.
- fnm is a fast Rust-based manager. Run fnm install 24, fnm use 24 and fnm default 24. Add eval "$(fnm env --use-on-cd)" to your shell profile so it switches when you cd into a project that has a .nvmrc or .node-version file.
- Volta installs tools per project. Run volta install node@24 to add it to your user toolchain, then volta pin node@24 inside a project to write the version into package.json.
- Corepack ships with Node 16.9 and later. It manages the package managers pnpm and yarn, and it can pin them with the packageManager field. It does not install or switch Node itself. Run corepack enable to turn it on.
Pin one Node version for a project
A pin is a file in the repository that names the major everyone should run. Put one in place, then make the Dockerfile and the CI workflow read the same value.
# .nvmrc (read by nvm and fnm)
echo "24" > .nvmrc
# .node-version (read by fnm, and by many other tools)
echo "24" > .node-version
# Volta: writes a "volta" block into package.json
volta pin node@24Enforce it with engines
The engines field in package.json documents the range a package supports. By default npm only warns when the running version does not match. Set engine-strict in .npmrc to make npm install fail instead.
{
"name": "my-app",
"engines": {
"node": ">=22 <27"
}
}Set the version in Docker and GitHub Actions
In a container, the Node version is whatever the FROM line names. Pin a major tag so a rebuild does not silently jump to a new major. For a production image that must never change, pin the digest as well.
# Pin the major and a variant
FROM node:24-bookworm-slim
# Stricter: pin the image digest too
# FROM node:24-bookworm-slim@sha256:<digest>
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
CMD ["node", "server.js"]In GitHub Actions, actions/setup-node can read the version straight from the pin file, so the workflow and your local machine stay aligned.
steps:
- uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version-file: '.nvmrc'
cache: npm
- run: npm ci
- run: npm testTroubleshoot the wrong or missing version
Start with two commands. which node shows the file the shell is running, and node -v shows its version. On Windows, use where node in place of which node.
which node # path of the node binary in use
type -a node # every node on PATH, in order
node -v # the version of that binary- command not found: node. The version manager is installed but not loaded in this shell. Open a new terminal, or source the manager in your profile, then run nvm use 24 again.
- Version changed after a Homebrew or installer update. A Homebrew or system Node earlier on PATH is shadowing nvm. Check type -a node, then put the version manager directory first or remove the old install.
- Shell still reports the old version after nvm use. Run hash -r in bash or zsh to clear the cached path of the binary.
- Node version differs between CI and local. CI is not reading your pin. Check that node-version-file points at the right file, and that the Dockerfile FROM line uses the same major.
- No version switch on cd. The project has no .nvmrc or .node-version file, or the shell hook for fnm or nvm is not in your profile.
- npm install fails with an engines error. engine-strict is on and the running version is outside the range in package.json. Switch to a supported version, or widen the range only after you have tested it.
How SeaGit picks the Node version
SeaGit builds apps from GitHub on push and deploys them to Amazon EKS in your own AWS account. Only AWS is supported as a target. A container build uses the Dockerfile at the repository root, so the Node version comes from that file. Set the FROM line to the major you want, and the build uses the same runtime as your pin file.
If the repository has no Dockerfile at the root, the default build fails with a message saying no Dockerfile was found. Add one, then push again to start a new build.