How to Check Your Node.js Version (All Methods)

Node version mismatches are one of the most common causes of builds failing, packages refusing to install, and scripts behaving differently on your machine than on a teammate's or a CI server. Before you chase down any of those problems, you need to know exactly which Node version is active. This guide covers every method — from the one-liner you can run right now to checking what version a specific project expects.

The Quickest Way: node --version

Run this in any terminal:

node --version
# v20.11.0

The -v shorthand does the same thing:

node -v
# v20.11.0

This prints the version of Node.js currently on your PATH. If you see command not found, Node is either not installed or the install directory is not in your PATH. On macOS and Linux that usually means the shell config (~/.zshrc, ~/.bashrc) was not sourced after installation — open a new terminal tab and try again.

You can also check the npm version at the same time:

node -v && npm -v
# v20.11.0
# 10.2.4

npm ships with Node, but its version does not always map directly to the Node version. Checking both is useful when a package's install instructions reference a minimum npm version.

Check Node Version Inside a Project

What version does this project expect?

A project declares its required Node version in one of three places. The most reliable answer is usually the engines field in package.json:

cat package.json | grep -A 3 '"engines"'
# "engines": {
#   "node": ">=18.0.0"
# },

If there is no engines field, look for a .nvmrc or .node-version file in the project root:

cat .nvmrc
# 20.11.0

cat .node-version
# 20.11.0

Both files serve the same purpose — they tell your version manager which Node version to activate when you enter the directory. The difference is which tools read them: nvm reads .nvmrc, Volta and asdf read .node-version (though nvm also reads .node-version as a fallback).

If none of these files exist and there is no engines field, check the CI config (/.github/workflows/*.yml, vercel.json, .circleci/config.yml) — that is often the most accurate record of what version the project actually runs on.

Check what version Vercel will use

If you are deploying to Vercel, the Node version is set in your project's dashboard under Settings → General → Node.js Version, or overridden by the engines field in package.json. A mismatch between your local version and Vercel's build version is a frequent cause of Vercel build failures that only surface in CI.

Check Node Version with nvm

Which version is active right now?

nvm current
# v20.11.0

List every installed version

nvm ls
#        v18.19.0
# ->     v20.11.0
#        v21.6.0
# default -> 20.11.0 (-> v20.11.0)
# node -> stable (-> v21.6.0) (default)
# stable -> 21.6.0 (-> v21.6.0) (default)

The arrow (->) marks the active version. The default alias controls which version opens in new terminal windows.

Check the default version

nvm alias default
# default -> 20.11.0 (-> v20.11.0)

This matters because nvm use in a project only affects the current shell session. If you close the terminal and come back, the default alias is what activates. If your default is an old version and a project's .nvmrc says otherwise, the version nvm activates depends on whether you ran nvm use — or whether your shell is configured to run it automatically.

Why Your Node Version Matters

Why does running the wrong Node version break things?

Running the wrong Node version causes a predictable set of failures. The most common: native module compilation errors (like node-gyp failures), peer dependency conflicts during npm install, and syntax errors if a package uses JavaScript features not available in older Node releases.

Each Node.js release has a defined support window. The Node.js release schedule distinguishes between Active LTS, Maintenance LTS, and End-of-Life versions. Most package maintainers test against Active LTS. When you run a version outside that range — especially one that is End-of-Life — you are in territory the package author never validated.

The practical impact:

• npm install fails — some packages use engines field enforcement or have optional native dependencies that only compile against specific Node ABI versions
• TypeScript compilation behaves differently — tsc output can vary across Node versions because the underlying V8 engine changes
• Build tools break — Webpack, Vite, and Next.js all have documented Node version requirements, and falling below the minimum produces errors that look unrelated to Node at first glance
• Tests pass locally, fail in CI — almost always a version mismatch; npm peer dependency conflicts frequently trace back to a Node version the lockfile was not generated with

This is also why TypeScript build errors on Vercel sometimes appear only in CI: the build environment may be running a different Node version than the one you tested locally.

The Node version check you should run before anything else

Before you install a new package, run npm install on a cloned repo, or try to debug a mysterious build error, run node -v. Then check what the project expects. Thirty seconds of version verification prevents an hour of chasing the wrong problem.

This is especially true if you use a version manager and work across multiple projects. Your shell's active version is whatever nvm use or Volta last set it to — and if you opened a new terminal tab or switched projects without re-running the activation, you might be on an entirely different version than you think. The Node.js Long Term Support schedule is a useful reference for understanding which versions are still receiving security patches and which ones packages are most likely to support.

How to Switch Node Versions

With nvm

# Switch to a specific version
nvm use 20.11.0

# Switch to the latest LTS
nvm use --lts

# Install a version you do not have yet, then switch to it
nvm install 20 --lts && nvm use 20

If the project has a .nvmrc file, just run nvm use with no arguments:

nvm use
# Found '/path/to/project/.nvmrc' with version <20.11.0>
# Now using node v20.11.0 (npm v10.2.4)

With Volta

Volta pins versions per-project rather than per-shell:

# Pin Node 20 for the current project (writes to package.json)
volta pin node@20

# Check what Volta has pinned
cat package.json | grep -A 5 '"volta"'
# "volta": {
#   "node": "20.11.0"
# }

Once pinned, Volta automatically activates the right version whenever you run a Node command inside the project directory — no nvm use required.

With asdf

# List installed Node versions
asdf list nodejs

# Set a version locally (writes .tool-versions)
asdf local nodejs 20.11.0

# Check the active version
asdf current nodejs
# nodejs  20.11.0  /path/to/project/.tool-versions

Node Version Managers Compared

Choosing between nvm, Volta, and asdf comes down to how much automation you want and whether you need to manage runtimes beyond Node.

| Feature | nvm | Volta | asdf | |---|---|---|---| | Language support | Node only | Node + npm + Yarn | Any runtime via plugins | | Version activation | Manual (nvm use) or shell hook | Automatic per-project | Manual (asdf shell) or .tool-versions | | Per-project pinning | .nvmrc | package.json volta field | .tool-versions | | CI-friendly | Requires shell sourcing | Yes, binary-based | Yes, with plugin install | | Windows support | Separate project (nvm-windows) | Yes | Limited (WSL recommended) | | Install speed | Shell function, slower startup | Fast binary | Shell function | | Docs | nvm GitHub | Volta docs | asdf docs |

Use nvm if you are already using it and it is working. It is the most widely documented option and most Stack Overflow answers assume it.

Use Volta if you work across multiple projects with different Node requirements and want activation to be automatic. It is especially good on teams — once a version is pinned in package.json, everyone gets the same version without remembering to run nvm use.

Use asdf if you also manage Python, Ruby, Go, or other runtimes and want a single tool for all of them.

Direct install (no version manager) only makes sense for production servers with a single known Node requirement. On a development machine, you will eventually need multiple versions.

When Your Node Version Is Causing Build Failures

Version mismatch failures often masquerade as something else. Here are the patterns to recognize:

The build works locally but fails in CI. Check the CI config and compare the Node version it specifies against your local version. A one-major-version difference is enough to break packages with strict engines ranges.

npm install produces peer dependency warnings or errors. The lockfile was generated on a different Node version. Delete node_modules and package-lock.json, set the correct Node version, and reinstall from scratch. npm peer dependency conflicts are almost always easier to resolve once the Node version matches what the project expects.

Hydration errors in Next.js apps. Less obvious, but if the server-side render runs on a different Node version than expected — or if a polyfill behaves differently across versions — you can get React hydration mismatches that look like a component bug but are actually an environment problem.

The error message mentions an ABI, NAPI, or node-pre-gyp. These are native modules. They compile against a specific Node ABI version. If you upgrade Node and the pre-built binary was not compiled for that version, you need to rebuild: npm rebuild or reinstall the package.

Node version checks to run when debugging any build failure:

# What is active right now
node -v

# What the project expects
cat .nvmrc 2>/dev/null || cat .node-version 2>/dev/null || node -e "const p=require('./package.json'); console.log(p.engines?.node || 'not specified')"

# What CI is running (if using GitHub Actions)
grep -r "node-version" .github/workflows/

If these three outputs do not agree, you have found your problem.

When the environment itself is the bug

Node version mismatches are a great example of a class of bugs where the code is fine — the environment is wrong. AI tools are particularly poor at diagnosing these because they cannot see your actual runtime state: what version manager you have installed, whether a shell hook is configured, what your PATH looks like, or what your CI environment actually resolves to.

A senior developer looking at your screen can spot this in under two minutes. They will run node -v, check your .nvmrc, look at the CI config, and have a diagnosis before you have finished explaining the symptom.

If you are stuck on a build failure that you cannot reproduce reliably or cannot explain, that is exactly the kind of problem FlowQL handles. You get a live 30-minute screen share with a vetted senior engineer. If they cannot resolve it, you pay nothing. Version mismatches, environment conflicts, dependency hell — these are solved problems for someone who has seen them a hundred times.

Conclusion

Checking your Node.js version is a one-liner — node -v or node --version. But understanding which version is active, why it matters, and what to do when it does not match what a project expects takes a bit more context.

The short version:

• Use node -v to check what is active
• Use nvm ls, volta list, or asdf list nodejs to see everything installed
• Look for .nvmrc, .node-version, or the engines field in package.json to find what a project requires
• Match them up before running npm install or starting a build

Most Node version problems are solved the moment you recognize them. The tricky part is recognizing them — because the error message is almost never "wrong Node version."

For more on diagnosing environment-related failures, see the guide to Vercel build failures.