How to automatically switch nodejs versions through pnpm env when running a project?

[A81N9]

How to automatically switch nodejs versions through pnpm env when running a project?

[shreyanshjain1]

pnpm env can manage and run different Node versions, but as far as I know it does not act like nvm, fnm, or volta where just entering a project directory automatically switches your shell to the project’s Node version.

So I would split it like this:

• pnpm env = install / use Node versions through pnpm
• automatic per-project shell switching = usually handled by a version manager that watches .nvmrc, .node-version, or similar

If your goal is true automatic switching when entering/running a project, then pnpm env by itself is probly not the best fit for that workflow.

The practical options are usually:

1. keep using pnpm env, but explicitly run the project with the desired Node version
2. use a dedicated Node version manager for auto-switching
3. define the required Node version in the project (package.json engines / .nvmrc / .node-version) and let your tooling enforce it

So my guess would be:

• no, pnpm env alone is not meant to auto-switch your active shell Node version just because you entered a project
• it is more of a version management / execution helper than a directory-watching version switcher

If what you want is the “cd into project and Node changes automatically” experience, I’d usually reach for something like fnm, nvm, or volta instead, then keep pnpm focused on package management.

If this helps, feel free to mark it as the answer so others can find it faster.

[zkochan]

If you run pnpm node, the version of node will automatically be switched to the one declared in the project. Just running node runs the globally installed version. In general you don't directly run node in a project. Instead, you have scripts that you run via pnpm run. Node.js in the scripts is managed by pnpm too. IMO there is no need in a dedicated Node version manager for auto-switching.

[shreyanshjain1]

That makes sense, thanks.

So if I understand correctly, pnpm doesn’t really “auto-switch” the shell’s global node binary when you enter a project.

Instead, the intended workflow is that:

• pnpm node
• and pnpm run ...

already use the project-managed Node version, so you still get the correct version when running the project the pnpm way.

So in that sense, the answer is basically “use pnpm node / pnpm run rather than expecting plain node itself to switch automatically”.

[zkochan]

yes, we don't switch the node.js version.

[pat721]

Sorry to dig this up again. If I understood the answers correctly, pnpm run is supposed to pickup the correct node version independent from the current node version running in the shell?

Because my shell is running node 24, however my project requires node 22 via package.json and pnpm-workspace.yaml. Whenever I run any pnpm run command, I get a Unsupported engine: wanted: {"node":"22.22.2"} (current: {"node":"v24.15.0","pnpm":"11.0.0"}). And I'm not sure if this is normal behaviour and I should actively switch the node version in my shell before running any commands, or if pnpm should automaticall switch to the correct version.

[chrisjcthomas]

The pnpm docs describe pnpm env as a way to install/use Node versions, and they also document project runtime settings like:

useNodeVersion: 16.16.0

and executionEnv.nodeVersion for package-level runtime selection.

That points to pnpm managing which Node runtime it uses for pnpm-driven execution (pnpm run, pnpm node, etc.), not acting like a shell-integrated directory watcher that auto-switches your active Node version when you cd into a project.

So I don't think pnpm env by itself gives the classic "enter directory and my shell Node version changes automatically" workflow the way tools like nvm, fnm, or volta do.

If your goal is automatic shell switching, I'd still use a dedicated version manager for that. If your goal is "this project should run with a specific Node version under pnpm", the documented pnpm-native path is useNodeVersion / executionEnv.nodeVersion.

[zkochan]

pnpm v11 has different settings for runtime configuration. I am not sure how frequently anyone runs "node" directly, not via a script in "package.json". But directly it will work too if you run "pnpm node" instead of "node". Using pnpm to manage the runtime is much better in my opinion as pnpm cli treats it as just another dependency and stores the resolved versions of node with integrity checksums of artifacts in the lockfile.

If we ever decide to make a bin jumper for node, then we should make all globally installed packages to behave same. So if "node" will automatically switch to the local node, then "eslint" should also automatically switch to the locally installed version of eslint. If that is the behaviour that most of our users would want, I don't have objections to do that.

[Lydanne]

I would like pnpm to be an alternative to setup-node in CI