Node.js Version Management

fnm provides powerful version management features, allowing you to easily switch between multiple Node.js versions.

Basic Operations

View Installed Versions

fnm list

Output example:

* v20.10.0 default
  v18.19.0
  v16.20.2

• * indicates the currently used version
• default indicates the default version

View Current Version

fnm current

Switch Version

# Switch to specific version
fnm use 20

# Switch to specific exact version
fnm use 20.10.0

# If version is not installed, auto install then switch
fnm use 18 --install-if-missing

Default Version

Set Default Version

fnm default 20

The default version is:

• The version used when a new terminal session starts
• The version used when there's no version file

View Default Version

fnm default

Version Aliases

Aliases allow you to set easy-to-remember names for versions.

Create Alias

# Set alias for version
fnm alias 20 default
fnm alias 18 legacy
fnm alias 16 old

Use Alias

# Switch version via alias
fnm use default
fnm use legacy

Delete Alias

fnm unalias legacy

Automatic Version Switching

fnm can automatically switch Node.js versions based on the project directory.

Enable Automatic Switching

Add --use-on-cd to Shell configuration:

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

Create Version File

Create a .node-version or .nvmrc file in the project root:

# Using .node-version (recommended)
echo "20" > .node-version

# Or using .nvmrc (compatible with nvm)
echo "v18.17.0" > .nvmrc

Version File Format

.node-version supports the following formats:

20           # Major version, use latest 20.x.x
20.10        # Minor version, use latest 20.10.x
20.10.0      # Exact version
lts/iron     # LTS version name

Version File Parsing Strategy

fnm supports two version file parsing strategies:

# local (default) - Only search in current directory
fnm env --version-file-strategy=local

# recursive - Recursively search parent directories
fnm env --version-file-strategy=recursive

package.json engines Support

fnm can read the engines.node field from package.json:

{
  "engines": {
    "node": ">=18.0.0"
  }
}

Enabled by default, can be disabled via environment variable:

export FNM_RESOLVE_ENGINES=false

Version Management Best Practices

1. Project-Level Version Locking

Create a .node-version file in each project:

cd my-project
echo "20" > .node-version
fnm install
fnm use

2. Team Collaboration

Add .node-version to Git:

git add .node-version
git commit -m "chore: add .node-version"

3. CI/CD Configuration

Use fnm in CI/CD environments:

# GitHub Actions
- name: Install fnm
  run: curl -fsSL https://fnm.vercel.app/install | bash

- name: Install Node.js
  run: fnm install && fnm use

4. Multi-Version Development

# Install multiple versions
fnm install 20
fnm install 18
fnm install 16

# Set aliases for easy switching
fnm alias 20 current
fnm alias 18 legacy
fnm alias 16 old

# Use different versions in different projects
cd project-new && fnm use current
cd project-old && fnm use legacy

Uninstall Versions

# Uninstall specific version
fnm uninstall 16.20.2

# Uninstall via alias (will delete version and all related aliases)
fnm uninstall old

Common Issues

node Command Doesn't Update After Version Switch

Ensure Shell configuration is correct:

# Check node path
which node

# Should point to fnm directory
# ~/.fnm/node-versions/.../bin/node

Automatic Switching Not Working

1. Confirm --use-on-cd is added to Shell configuration
2. Confirm version file exists
3. Reload Shell configuration

Version File Priority

fnm searches for versions in the following order:

1. Version specified on command line
2. .node-version file
3. .nvmrc file
4. package.json engines.node
5. Default version

Related Links

• Install Node.js - Installation guide
• Command Reference - All command details
• Download Management - Download related features