nodenv makes every Node.js version feel native. nodenv makes every Node.js version feel native. nodenv makes every Node.js version feel native.
Switch between project-specific Node.js versions with a clean, predictable workflow built for developers who value speed, consistency, and control.
What is nodenv?
nodenv is a lightweight Node.js version manager built for developers who work with different projects on the same machine. It allows multiple Node.js versions to remain installed at once, while each project can use the version it actually requires. This is important because older applications, modern frameworks, testing environments, and production setups may depend on different Node.js releases. Developers, software teams, package maintainers, and anyone managing several Node.js projects can use nodenv to keep their workflow consistent.
Instead of manually removing one Node.js installation and replacing it
with another, nodenv switches versions through simple command-line
controls. A project can store its selected version in a
.node-version file, making the requirement clear whenever
the project is opened. It also avoids relying on one machine-wide
version for every application. This keeps development environments
organized, reduces version conflicts, and helps team members run
projects with matching Node.js setups without repeatedly changing the
system installation.
| Software Type | Node.js version manager |
|---|---|
| Main Purpose | Manage multiple Node.js versions |
| Supported Environment | Unix-like operating systems |
| Configuration File | .node-version |
| Interface | Command line |
| Project Type | Open source |
Built for Flexible Development
Key Features of nodenv
Explore the core capabilities that make nodenv a practical choice for keeping Node.js versions organized across projects, terminals, and development workflows.
Multiple Node.js Versions
Keep several Node.js versions installed without repeatedly removing and reinstalling them.
Project-Specific Versions
Assign a separate Node.js version to each project using a .node-version file.
Global Version Control
Select a default Node.js version for projects that do not have a local configuration.
Automatic Version Switching
Move between project directories and let nodenv activate the configured version automatically.
Lightweight Command-Line Workflow
Manage versions through simple terminal commands without a complicated graphical interface.
Shell Integration
Use nodenv with common shell environments after completing the required initialization.
Extensible Plugin System
Add functionality through plugins for installation, package management, aliases, environment variables, and other workflows.
Isolated Global Packages
Global npm packages remain associated with the currently active Node.js installation.
Behind the command
How Does nodenv Work?
nodenv uses lightweight command shims to detect the Node.js version selected for a project and route each command to the correct installation automatically.
nodenv Joins Your PATH
nodenv adds its shims to the command lookup process.
You Run a Node.js Command
The process begins when you use commands such as node, npm, or npx.
nodenv Finds the Required Version
It checks the project directory for .node-version and identifies the selected Node.js release.
The Correct Node.js Version Runs
nodenv locates the matching installation inside its versions directory and runs the command with it.
Command resolution flow
Solve Everyday Version Problems
Why Use nodenv for Node.js Development?
Different projects often depend on different Node.js releases. nodenv helps keep those requirements separate and visible, so developers can move between codebases without repeatedly changing the system setup or risking version-related problems.
Prevent Version Conflicts Between Projects
When two projects require different releases, each can use its own version instead of competing for one shared installation.
Maintain Legacy and Modern Applications
Older applications can stay on the release they support while newer projects use a current Node.js version on the same machine.
Create Consistent Team Environments
A shared version file gives team members a clear project requirement and reduces differences between individual development setups.
Test Across Multiple Node.js Versions
Developers can switch releases when checking compatibility instead of uninstalling one version before every test cycle.
Reduce Manual Environment Configuration
Once a project version is defined, nodenv handles selection automatically and removes repeated setup work from everyday development.
Keep Project Versions Easy to See
The .node-version file records the expected release inside the project rather than leaving it as an undocumented local setting.
Simplify Moving Between Projects
Changing directories can activate the required version, making frequent movement between development projects less disruptive.
Avoid Replacing the System Node.js Installation
Project versions remain separate, so developers do not need to overwrite the system installation whenever requirements change.
Setup by Operating System
How to Install nodenv
Choose your operating system to see the recommended installation route, shell setup, verification command, and the next step for installing Node.js versions.
Recommended package route
Install on macOS with Homebrew
Homebrew provides the simplest setup path and installs the supporting node-build dependency used for adding Node.js versions.
- PrerequisitesHomebrew and a supported terminal shell.
- Install nodenvUse the Homebrew package command.
- Initialize the shellLet nodenv update the relevant shell configuration.
- Restart TerminalOpen a new window or tab to apply PATH changes.
- Verify setupConfirm the nodenv command is available.
- Next stepList available releases, then install the Node.js version you need.
# Install nodenv and node-build
brew install nodenv
# Configure your current shell
nodenv init
# Close and reopen Terminal, then verify
nodenv --version
# Next: browse and install Node.js
nodenv install -l
nodenv install <node-version>Git installation recommended
Install on Ubuntu or Debian
Because nodenv is not supplied through the standard Debian or Ubuntu repositories, use a Git checkout and prepare the build tools required by node-build.
- PrerequisitesInstall Git, a downloader, compiler tools, and SSL development headers.
- Clone nodenvPlace the latest Git checkout in your home directory.
- Initialize the shellRun nodenv init from the cloned binary.
- Restart the shellOpen a new terminal tab or reload your shell.
- Verify setupCheck that nodenv responds from the command line.
- Next stepAdd node-build so the nodenv install command becomes available.
# Install required tools
sudo apt update
sudo apt install -y git curl build-essential libssl-dev
# Clone and initialize nodenv
git clone https://github.com/nodenv/nodenv.git ~/.nodenv
~/.nodenv/bin/nodenv init
# Restart Terminal, then verify
nodenv --version
# Add Node.js installation support
git clone https://github.com/nodenv/node-build.git "$(nodenv root)"/plugins/node-build
nodenv install -lGit installation recommended
Install on Fedora
Fedora users can install the required development tools first, then use the upstream Git checkout because nodenv is not currently included in Fedora’s standard repositories.
- PrerequisitesPrepare Git, curl, compilers, make, and OpenSSL development files.
- Clone nodenvInstall it locally inside your home directory.
- Initialize the shellRun the init helper from the cloned installation.
- Restart TerminalStart a fresh shell session to apply the changes.
- Verify setupConfirm the version manager is available.
- Next stepInstall node-build and choose a Node.js release.
# Install required tools
sudo dnf install -y git curl gcc gcc-c++ make openssl-devel
# Clone and initialize nodenv
git clone https://github.com/nodenv/nodenv.git ~/.nodenv
~/.nodenv/bin/nodenv init
# Restart Terminal, then verify
nodenv --version
# Add Node.js installation support
git clone https://github.com/nodenv/node-build.git "$(nodenv root)"/plugins/node-build
nodenv install -lCommunity package route
Install on Arch Linux
Arch Linux provides a community-maintained nodenv package through the AUR. Review the PKGBUILD, build the package locally, and then initialize your shell.
- PrerequisitesInstall Git and the base-devel tool group used for AUR builds.
- Get the AUR packageClone the community nodenv package repository.
- Build and installInspect the files, then build the package with makepkg.
- Initialize and restartConfigure nodenv and open a fresh terminal session.
- Verify setupCheck that the command is working correctly.
- Next stepAdd node-build through the optional AUR package or Git plugin.
# Prepare the AUR build environment
sudo pacman -S --needed base-devel git
# Clone, review, build, and install nodenv
git clone https://aur.archlinux.org/nodenv.git
cd nodenv
makepkg -si
# Initialize, restart Terminal, then verify
nodenv init
nodenv --version
# Next: add node-build support
git clone https://github.com/nodenv/node-build.git "$(nodenv root)"/plugins/node-buildDirect control
Install nodenv Manually with Git
Use a basic Git checkout when you prefer a user-level installation without a system package manager or want direct control over updates.
- PrerequisitesGit, a Unix-like shell, and build dependencies for Node.js installation.
- Clone nodenvKeep the installation inside
~/.nodenv. - Initialize the shellRun the built-in setup helper for your active shell.
- Restart the shellOpen a new terminal session to load nodenv shims.
- Verify setupConfirm nodenv is available before installing Node.js.
- Next stepAdd node-build, list releases, and select a local or global version.
# Clone nodenv into your home directory
git clone https://github.com/nodenv/nodenv.git ~/.nodenv
# Configure the active shell
~/.nodenv/bin/nodenv init
# Restart Terminal, then verify
nodenv --version
# Install the node-build plugin
git clone https://github.com/nodenv/node-build.git "$(nodenv root)"/plugins/node-build
# Choose the next action
nodenv install -l
nodenv install <node-version>nodenv install command is supplied by the node-build plugin. Build tools and development libraries should be available before installing a Node.js release.First Version Setup
Install and Activate Your First Node.js Version
Install a Node.js release, choose it as your default, or assign it only to a specific project. These two short workflows confirm that nodenv is selecting the version you expect.
Install a release, set it as the default Node.js version, then verify the active runtime.
nodenv install <node-version>
nodenv global <node-version>
node --version
Open the project directory, assign its Node.js version, and confirm the active runtime.
cd your-project
nodenv local <node-version>
node --version
nodenv local changes
The command creates or updates a .node-version file in the current directory. When you return to that project, nodenv reads this file and selects the assigned Node.js release.
Command Reference
Essential nodenv Commands
Use these core commands to inspect installed versions, control project and shell environments, locate the active Node.js executable, and maintain nodenv command shims.
| Command | Purpose |
|---|---|
nodenv versions |
Display installed Node.js versions. |
nodenv version |
Show the currently active version. |
nodenv install |
Install a Node.js version through node-build. |
nodenv local |
Set a version for the current project. |
nodenv global |
Set the default Node.js version. |
nodenv shell |
Select a version for the current shell session. |
nodenv which node |
Show the active Node.js executable. |
nodenv prefix |
Display the installation path. |
nodenv rehash |
Rebuild command shims. |
nodenv uninstall |
Remove a version when supported by node-build. |
Version Priority
Understanding nodenv Version Selection
nodenv can use a project-specific version, a machine-wide default, or a temporary shell setting. The three options below show where each one applies and which setting takes priority when more than one is present.
Local Version
Used for one project or directory through .node-version. It is the usual choice when a specific app needs its own Node.js release.
Global Version
Used as the machine’s default when no project-specific version is configured. It keeps a standard Node.js version available across the system.
Shell Version
Temporarily selected for the current terminal session. It is useful when you want to test a different version without changing project or global settings.
Example scenario
Imagine your global version is set to 18.20.0, but a project folder contains a .node-version file with 20.11.1. If you also run a shell-specific version command, nodenv checks these settings in priority order.
Priority order
When more than one setting exists, nodenv follows this order from highest to lowest:
.node-version inside the current project or directory.
Balanced Comparison
nodenv vs NVM and Other Version Managers
nodenv and NVM both help developers work with multiple Node.js versions, but they use different approaches. This comparison highlights their configuration style, architecture, project files, and the workflows each tool commonly supports.
| Area | nodenv | NVM |
|---|---|---|
| Version switching | Directory-based configuration | Shell-based commands |
| Project file | .node-version |
Commonly .nvmrc |
| Architecture | Shims and PATH integration | Shell function integration |
| Plugin support | Available | Different extension model |
| Best suited for | Project-focused Unix workflows | Broad shell-based workflows |
Practical Scenarios
When Should You Use nodenv?
nodenv becomes most useful when different projects, teams, or deployment targets need predictable Node.js versions. These common situations show where version management saves time and avoids confusion.
Maintaining an older Node.js application
Older projects often depend on a specific Node.js release that newer apps no longer use. nodenv lets you keep that version available without disturbing the rest of your development setup.
Testing a package across multiple Node.js versions
If you publish a package, you may need to confirm that it works across several supported releases. nodenv makes it easier to switch versions quickly and run the same test flow again.
Working on several projects with different requirements
One project may need an older runtime while another expects a newer release. With nodenv, each folder can keep its own version so you do not have to keep reinstalling Node.js.
Matching local development with production
Differences between your local machine and the production environment can lead to avoidable issues. nodenv helps you run the same Node.js version locally that your deployment target is expecting.
Standardizing Node.js versions across a development team
Teams work more smoothly when everyone uses the same runtime version. A simple .node-version file helps new and existing team members stay aligned without extra guesswork.
Preparing a repeatable development environment
Repeatable setups are useful for onboarding, rebuilding machines, or moving between systems. nodenv keeps version selection predictable, which makes development environments easier to reproduce.
Common Questions
Frequently Asked Questions About nodenv
Find clear answers about installing nodenv, selecting Node.js versions, working with project files, managing npm packages, using plugins, and resolving common command issues.
nodenv is used to manage multiple Node.js versions on one Unix-like system. It selects the correct runtime for each project, usually by reading a .node-version file, so developers can move between applications with different requirements without repeatedly replacing the system installation.
nodenv is primarily a version manager, not a complete Node.js installer by itself. The commonly used nodenv install command is supplied by the separate node-build plugin, which downloads and builds Node.js releases for use inside the nodenv versions directory on your machine.
nodenv is designed for Unix-like operating systems and is not presented as a native Windows version manager. Windows users may run it inside a compatible Unix-like environment such as WSL, while a Windows-focused Node.js version manager may be more suitable for a fully native workflow.
On macOS, the recommended package-manager method is Homebrew. Run brew install nodenv, execute nodenv init to configure shell startup, and then close and reopen the terminal. After that, verify the command works and install node-build if you need nodenv install.
For Ubuntu and Debian-based systems, the project recommends a Git installation because nodenv is not currently available through their standard repositories. Install the required build tools, clone nodenv into ~/.nodenv, run its initialization command, restart the shell, and verify the setup before installing Node.js.
The .node-version file stores the Node.js version assigned to a project or directory. Running nodenv local <version> creates or updates this file. When you enter that directory, nodenv reads it and selects the matching installed runtime automatically for commands such as Node.js, npm, and npx.
A local version applies to a specific project or directory and is stored in .node-version. A global version is the default used when no local setting exists. Local configuration takes priority over global configuration, while a shell-specific version can temporarily override both.
Run nodenv versions to display the Node.js versions known to nodenv. The currently active version is marked with an asterisk, and the output can also indicate which configuration selected it. Use nodenv version when you only need the active version.
Use nodenv local <version> for the current project, nodenv global <version> for the default environment, or nodenv shell <version> for a temporary terminal session. The requested release must already be installed. Confirm the result with node --version or nodenv version before continuing your work.
The nodenv install command is not included in the core nodenv package. It is provided by the node-build plugin. Install that plugin inside the nodenv plugins directory, restart or reload your shell if needed, and then check the available installation commands again.
When node-build is installed, use nodenv uninstall <version> to remove a managed Node.js release. The documentation also explains that a version can be removed by deleting its directory under ~/.nodenv/versions. Check that no active project still depends on it first.
nodenv does not replace npm or directly manage project dependencies. You continue using npm normally after selecting a Node.js version. Globally installed packages are scoped to the active Node.js version, and the optional nodenv-default-packages plugin can install a chosen set for new versions.
nodenv rehash rebuilds the shim files for executables available in installed Node.js versions. You may need it after installing or removing global packages so newly added commands can be found through your PATH. The optional nodenv-package-rehash plugin can automate this process during package changes.
Core nodenv uses files such as .node-version, but the optional nodenv-package-json-engine plugin can select a compatible installed version from package.json under engines.node. When a version range is provided, the plugin chooses a matching installed release. A shell-level selection or .node-version file still takes priority.
Yes. nodenv is a free, open-source project distributed under the MIT License. Its source code, documentation, issue tracker, and contribution workflow are publicly available. Users can inspect the implementation, report problems, propose improvements, or build optional plugins around its shell-based extension system.