Managing Node.js Versions on NixOS: A Comprehensive Guide

Step-by-Step Tutorial to Manage Node Versions on NixOS.

Rajdeep Singh

The Linux

· ~6 min read · February 5, 2025 (Updated: February 6, 2025) · Free: No

NixOS + Nodejs

In NixOS, you install the specific Node.js version according to your requirements, such as Node.js version 18, 20, 21, 22, etc.

Check out the following example to install node.js in your NixOS.

# installing nodejs package in system profile.
environment.systemPackages = with pkgs; [ nodejs_23 ];
# nodejs_22
environment.systemPackages = with pkgs; [ nodejs_22 ];
# nodejs_20
environment.systemPackages = with pkgs; [ nodejs_20 ];

However, you can not install multiple node versions in NixOS. The following example explains this better.

environment.systemPackages = with pkgs; [ nodejs_22 nodejs_20 ]; # it not work.

The most effective method for installing the Node version in NixOS is to utilise the Node.js version manager.

Several Node.js version managers are accessible in the open-source server environment, including NVM, N, fnm, asdf, and Volta.

In this tutorial, we use the Fnm Node.js version manager, which is faster, simpler, and easier to use than other Node version managers. Fnm works with .node-version and .nvmrc files.

If you want to learn a comparison between different node versions, check out this tutorial: Node.js Version Managers — Install and Run Multiple Node.js Versions.

Step up

How to install the Fnm Node.js version manager in NixOS? · Shell Setup ∘ Bash Shell ∘ Zsh Shell ∘ Fish shell ∘ Configuration Option
How to use the Fnm Node.js version manager in NixOS? ∘ list-remote ∘ list ∘ install (Important) ∘ use (Important) ∘ default ∘ current ∘ uninstall
Conclusion

Demo

Fnm Demo

How to install the Fnm Node.js version manager in NixOS?

To use The Fnm Nodejs version, first install the Fnm package in NixOS.

// configuration.nix

environment.systemPackages = with pkgs; [
    fnm
];

// home-manager

home.packages = with pkgs; [ fnm ]

// nix-env

nix-env -iA nixos.fnm

Shell Setup

The next step is to set environment variables must be set up before using fnm in NixOS according to your shell, such as bash, zsh, etc.

Bash Shell

Add the following to your .bashrc profile:

eval "$(fnm env --use-on-cd --shell bash)"

Zsh Shell

Add the following to your .zshrc profile:

eval "$(fnm env --use-on-cd --shell zsh)"

Fish shell

Create ~/.config/fish/conf.d/fnm.fish and add this line to it:

fnm env --use-on-cd --shell fish | source

Fnm has another configuration to enable highly recommended features, like automatic version switching.

If you face the following error when you use fnm

➜  ~ fnm use "v22.13.1"    
error: We can't find the necessary environment variables to replace the Node version.
You should setup your shell profile to evaluate `fnm env`, see https://github.com/Schniz/fnm#shell-setup on how to do this
Check out our documentation for more information: https://fnm.vercel.app

That means you don't configure the fnm in the shell; first, complete the Shell Setup, then use it, and your error is solved.

Configuration Option

The --use-on-cd option is useful when changing directories. Fnm switches the Node.js version according to the current directory's requirements based on .node-version or .nvmrc (or packages.json#engines#node if — resolve-engines is enabled).

Check out the fnm configuration documentation for the other --version-file-strategy=recursive , --corepack-enabled , and --resolve-enginesoptions.

How to use the Fnm Node.js version manager in NixOS?

You can use Fnm very easily using Fnm CLI. With the Fnm CLI, you can install and manage the Node version in NixOS.

Check out all options in the fnm option using the fnm --help command.


➜  ~ fnm --help       
A fast and simple Node.js manager

Usage: fnm [OPTIONS] <COMMAND>

Commands:
  list-remote  List all remote Node.js versions [aliases: ls-remote]
  list         List all locally installed Node.js versions [aliases: ls]
  install      Install a new Node.js version
  use          Change Node.js version
  env          Print and set up required environment variables for fnm
  completions  Print shell completions to stdout
  alias        Alias a version to a common name
  unalias      Remove an alias definition
  default      Set a version as the default version
  current      Print the current Node.js version
  exec         Run a command within fnm context
  uninstall    Uninstall a Node.js version
  help         Print this message or the help of the given subcommand(s)

Options:
      --node-dist-mirror <NODE_DIST_MIRROR>
          <https://nodejs.org/dist/> mirror
          
          [env: FNM_NODE_DIST_MIRROR]
          [default: https://nodejs.org/dist]

      --fnm-dir <BASE_DIR>
          The root directory of fnm installations
          
          [env: FNM_DIR]

      --log-level <LOG_LEVEL>
          The log level of fnm commands
          
          [env: FNM_LOGLEVEL]
          [default: info]
          [possible values: quiet, error, info]

      --arch <ARCH>
          Override the architecture of the installed Node binary. Defaults to arch of fnm binary
          
          [env: FNM_ARCH]

      --version-file-strategy <VERSION_FILE_STRATEGY>
          A strategy for how to resolve the Node version. Used whenever `fnm use` or `fnm install` is called without a version, or when `--use-on-cd` is configured on evaluation
          
          [env: FNM_VERSION_FILE_STRATEGY]
          [default: local]

          Possible values:
          - local:     Use the local version of Node defined within the current directory
          - recursive: Use the version of Node defined within the current directory and all parent directories

      --corepack-enabled
          Enable corepack support for each new installation. This will make fnm call `corepack enable` on every Node.js installation. For more information about corepack see <https://nodejs.org/api/corepack.html>
          
          [env: FNM_COREPACK_ENABLED]

      --resolve-engines
          Resolve `engines.node` field in `package.json` whenever a `.node-version` or `.nvmrc` file is not present.
          Experimental: This feature is subject to change.
          Note: `engines.node` can be any semver range, with the latest satisfying version being resolved.
          
          [env: FNM_RESOLVE_ENGINES]

  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

In this tutorial, we learn only the most important options that you use daily in your life.

list-remote
list
install
use
default
current
uninstall