Node.js virtual environment builder
raw JSON → 1.10.0 verified Sat Apr 11 auth: no python quickstart: stale
Nodeenv is a Python tool that facilitates creating isolated Node.js environments, similar to how `virtualenv` manages Python environments. It allows developers to install specific Node.js versions and global npm packages within a dedicated directory, preventing conflicts between different projects. Currently at version 1.10.0, the library maintains an active development pace with several releases per year, incorporating new Python and Node.js version support, as well as bug fixes and improvements like UV virtual environment integration.
pip install nodeenv Common errors
error 'nodeenv' is not recognized as an internal or external command, operable program or batch file ↓
cause The `nodeenv` executable is not in the system's PATH environment variable, typically after a global pip installation on Windows without a system-wide PATH update, or if the terminal session hasn't been restarted.
fix
Ensure Python's script directory (e.g.,
C:\PythonXX\Scripts or C:\Users\YourUser\AppData\Roaming\Python\PythonXX\Scripts) is added to your system's PATH environment variable, then restart your terminal or IDE. error nodenv: command not found ↓
cause The `nodeenv` executable is not found in the shell's PATH. This usually occurs after installation if the Python script directory is not included in the shell's PATH, or if running on Linux/macOS and the installation location (e.g., `~/.local/bin`) is not sourced.
fix
Add the directory where
pip installs scripts (e.g., export PATH=$PATH:~/.local/bin for Linux/macOS or the equivalent for your Python installation) to your shell's configuration file (e.g., ~/.bashrc, ~/.zshrc) and then source it or open a new terminal. error Command '['node', '-v']' failed with error code 1 ↓
error sh: node: command not found ↓
cause After creating a `nodeenv` environment, the Node.js or npm executables are not being found because the `nodeenv` environment has not been activated, or the installation of Node.js within `nodeenv` failed.
fix
Activate your
nodeenv environment using source /path/to/your/env/bin/activate. If the issue persists, try recreating the environment with a specific Node.js version using nodeenv my_env --node=lts. error Failed to download from https://nodejs.org/download/release/vX.X.X/node-vX.X.X-linux-x64.tar.gz ↓
cause `nodeenv` was unable to download the Node.js pre-built binaries, often due to network connectivity issues, corporate proxies, or SSL certificate problems preventing access to `nodejs.org`.
fix
If behind a proxy, set
http_proxy and https_proxy environment variables. For SSL certificate issues, try using the --ignore-ssl-certs flag when creating the environment: nodeenv my_env --ignore-ssl-certs. error no python virtualenv is available ↓
cause The `nodeenv -p` command is designed to install Node.js into an *existing and active* Python virtual environment, but no such environment is currently detected as active in your shell.
fix
First, activate your Python virtual environment (e.g.,
source /path/to/my/python_venv/bin/activate), then run nodeenv -p to install Node.js into it. Warnings
breaking Version 1.7.0 of `nodeenv` dropped support for Python versions 3.4, 3.5, and 3.6. Users on these Python versions must either upgrade their Python environment or pin `nodeenv` to a version older than 1.7.0. ↓
fix Upgrade Python to 3.7+ or constrain `nodeenv` version to `<1.7.0` (e.g., `pip install nodeenv<1.7.0`).
gotcha When using `nodeenv --python-virtualenv` (or `-p`) to integrate Node.js into a Python virtual environment, ensure your Python virtual environment is active. Running the command without an active Python venv will result in a 'no python virtualenv is available' error, even if `nodeenv` itself is installed. ↓
fix Always `source /path/to/your_venv/bin/activate` before running `nodeenv -p`.
gotcha Using the `--ignore_ssl_certs` option can bypass SSL certificate verification, which poses a security risk. This option should only be used in trusted environments and with full understanding of the implications. ↓
fix Avoid `--ignore_ssl_certs` unless absolutely necessary and ensure you understand the security implications. Prefer setting up proper SSL certificates or using a trusted mirror if network issues persist.
gotcha Initial `nodeenv` installation or Node.js compilation can appear to hang without output, especially on slower connections or when compiling from source. This is often due to large downloads or long compilation times. ↓
fix Use the `--verbose` flag for detailed output or the `--prebuilt` flag to prefer pre-compiled Node.js binaries for faster installation (`nodeenv --prebuilt`).
gotcha Shell commands (like `python -m venv` or `nodeenv` commands) placed directly within a Python script will result in a `SyntaxError` when the script is executed. These commands are not valid Python syntax. ↓
fix Execute shell commands directly in a shell (e.g., terminal or `.sh` script). If a shell command must be run from within a Python script, use Python's `subprocess` module (e.g., `subprocess.run(['python', '-m', 'venv', 'my_node_project'], check=True)`).
breaking Shell commands (like `python -m venv`) cannot be directly embedded and executed within a Python script. They must be executed using Python's `subprocess` module (e.g., `subprocess.run(['python', '-m', 'venv', 'my_node_project'], check=True)`) or `os.system('python -m venv my_node_project')`). Attempting to do so will result in a `SyntaxError`. ↓
fix To execute shell commands from within a Python script, use the `subprocess` module (e.g., `import subprocess; subprocess.run(['python', '-m', 'venv', 'my_node_project'], check=True)`) or `os.system()` (e.g., `import os; os.system('python -m venv my_node_project')`).
Quickstart stale last tested: 2026-04-23
# First, create and activate a Python virtual environment
python -m venv my_node_project
source my_node_project/bin/activate
# Install nodeenv into the active Python virtual environment
pip install nodeenv
# Create a Node.js virtual environment within the Python venv, installing a specific Node.js version
# The --python-virtualenv (-p) flag integrates it with the current Python venv
nodeenv --python-virtualenv --node=lts node_env
# Note: nodeenv modifies the activation scripts. Reactivate the Python venv
# or manually source the node_env/bin/activate script.
source my_node_project/bin/activate
# Verify Node.js and npm versions
node -v
npm -v
# Install a global npm package (e.g., `pnpm`)
npm install -g pnpm
# Deactivate the node environment when done
deactivate_node
# Then deactivate the Python virtual environment
deactivate