Node.js virtual environment
nodeenv (node.js virtual environment) is a tool to create isolated node.js environments.
It creates an environment that has its own installation directories, that doesn’t share libraries with other node.js virtual environments.
Also the new environment can be integrated with the environment which was built by virtualenv (python).
If you use nodeenv feel free to add your project on wiki: Who-Uses-Nodeenv.
Install
Global installation
You can install nodeenv globally with easy_install:
$ sudo easy_install nodeenv
or with pip:
$ sudo pip install nodeenv
or on Debian using dpkg:
$ ln -s debian-upstream debian $ dpkg-buildpackage -uc -us -b $ sudo dpkg -i $(ls -1rt ../nodeenv_*.deb | tail -n1)
Local installation
If you’re using virtualenv then you can install nodeenv via pip/easy_install inside any virtual environment built with virtualenv:
$ virtualenv env $ . env/bin/activate (env) $ pip install nodeenv (env) $ nodeenv --version 0.6.5
If you want to work with the latest version of the nodeenv you can install it from the github repository:
$ git clone https://github.com/ekalinin/nodeenv.git $ ./nodeenv/nodeenv.py --help
or with pip:
$ pip install -e git+https://github.com/ekalinin/nodeenv.git#egg=nodeenv
Dependency
For nodeenv
python (2.6+, 3.5+, or pypy)
make
tail
For node.js
libssl-dev
Usage
Basic
Create new environment:
$ nodeenv env
Activate new environment:
$ . env/bin/activate
On Windows the environment is created in env\Scripts instead, with a script per shell: activate.bat for cmd, Activate.ps1 for PowerShell and activate for posix shells such as git-bash:
$ . env/Scripts/activate
Check versions of main packages:
(env) $ node -v v0.10.26 (env) $ npm -v 1.4.3
Deactivate environment:
(env) $ deactivate_node
Advanced
Get available node.js versions:
$ nodeenv --list 0.0.1 0.0.2 0.0.3 0.0.4 0.0.5 0.0.6 0.1.0 0.1.2 0.1.3 0.1.4 0.1.5 0.1.6 0.1.7 0.1.8 0.1.10 0.1.11 0.1.12 0.1.13 0.1.14 0.1.15 0.1.16 0.1.18 0.1.19 0.1.20 0.1.21 0.1.22 0.1.23 0.1.24 0.1.26 0.1.27 0.1.28 0.1.29 0.1.30 0.1.31 0.1.32 0.1.90 0.1.91 0.1.92 0.1.93 0.1.94 0.1.95 0.1.96 0.1.98 0.1.99 0.1.100 0.1.101 0.1.102 0.1.103 0.1.104 0.2.1 0.2.2 0.2.3 0.2.4 0.2.5 0.2.6 0.3.0 0.3.2 0.3.3 0.3.4 0.3.5 0.3.6 0.3.7 0.3.8 0.4.1 0.4.2 0.4.3 0.4.4 0.4.5 0.4.6
Install node.js “0.4.3” without ssl support with 4 parallel commands for compilation and npm.js “0.3.17”:
$ nodeenv --without-ssl --node=0.4.3 --npm=0.3.17 --with-npm --jobs=4 env-4.3
Install node.js from the source:
$ nodeenv --node=0.10.25 --source env-0.10.25
Install node.js from a mirror:
$ nodeenv --node=10.19.0 --mirror=https://npm.taobao.org/mirrors/node
A local directory works as a mirror too, if it repeats the layout of nodejs.org: packages in v<version>/ and, to resolve latest, lts or a version range, an index.json next to them:
$ nodeenv --node=22.14.0 --mirror=file:///srv/node-mirror env-22
Install the highest node.js release matching a version range:
$ nodeenv --node=22 env-22 $ nodeenv --node=4.x env-4 $ nodeenv --node="^4.3.1" env-4.3 $ nodeenv --node=">=20 <22" env-20
Ranges use npm semver syntax and also work in a .node-version file.
It’s much faster to install from the prebuilt package than Install & compile node.js from source:
$ time nodeenv --node=0.10.25 --prebuilt env-0.10.25-prebuilt + Install node.js (0.10.25) ... done. real 0m6.928s user 0m0.408s sys 0m1.144s $ time nodeenv --node=0.10.25 --source env-0.10.25-src + Install node.js (0.10.25) ... done. real 4m12.602s user 6m34.112s sys 0m30.524s
Create a new environment with the system-wide node.js:
$ nodeenv --node=system
Use the system-wide node.js if it is available, otherwise install the latest LTS release:
$ nodeenv --prefer-system --node=lts env
Saving the versions of all installed packages to a file:
$ . env-4.3/bin/activate (env-4.3)$ npm install -g express (env-4.3)$ npm install -g jade (env-4.3)$ freeze ../prod-requirements.txt
If you want to list locally installed packages use -l option:
(env-4.3)$ freeze -l ../prod-requirements.txt
npm and corepack are installed by node.js itself and are left out of the list: pinning them would downgrade the copies the next node.js brings.
freeze saves the packages, not the runtime. To pin the node.js version as well, write it next to the requirements file - nodeenv reads .node-version from the directory it is run in:
(env-4.3)$ node --version > ../.node-version
Create an environment from a requirements file:
$ nodeenv --requirements=../prod-requirements.txt --jobs=4 env-copy
--requirements may be given more than once, and the packages of every file are installed globally:
$ nodeenv --requirements=../prod-requirements.txt \
--requirements=../dev-requirements.txt env-copy
To install packages locally, into node_modules of the current directory, use --local-requirements. It accepts the output of freeze -l and may also be given more than once:
$ nodeenv --requirements=../global-requirements.txt \
--local-requirements=../local-requirements.txt env-copy
Global packages are installed first, then the local ones.
Requirements files are plain text files that contain a list of packages to be installed. These text files allow you to create repeatable installations. Requirements file example:
$ cat ../prod-requirements.txt connect@1.3.0 express@2.2.2 jade@0.10.4 mime@1.2.1 qs@0.0.7
If you already have the python virtualenv tool, and want to use nodeenv and virtualenv in conjunction, then you should create (or activate) the python virtual environment:
# in case of using virtualenv_wrapper $ mkvirtualenv my_env # in case of using virtualenv $ . my_env/bin/activate
and add a node virtual environment to this existing new_venv:
$ nodeenv -p
If you need to set the path to make used to build node:
$ nodeenv -m /usr/local/bin/gmake ENV
That’s all. Now, all your node.js modules will be installed into your virtual environment:
$ workon my_env $ npm install -g coffee-script $ command -v coffee /home/monty/virtualenvs/my_env/bin/coffee
Creating a virtual environment with a custom prompt:
$ nodeenv –node=12.18.2 –prompt=”(myenv)” nodeenv
If environment’s directory already exists then you can use --force option:
$ nodeenv --requirements=requirements.txt --jobs=4 --force env
If you already have an environment and want to update packages from requirements file you can use --update option:
$ . env-4.3/bin/activate (env-4.3)$ nodeenv --requirements=requirements.txt --update env-4.3
If you want to call node from environment without activation then you should use shim script:
$ ./env-4.3/bin/shim --version v0.4.3
Command Line Options
Basic options
- -n NODE_VER, --node=NODE_VER
The node.js version to use, e.g., --node=22.11.0. Also accepts an npm-style semver range, which is resolved to the highest matching release: --node=22, --node=4.x, --node="^4.3.1", --node="~4.3", --node=">=20 <22", --node="8 || 10". The default is the last stable version (latest). Use lts for the latest LTS release. Use system to use system-wide node.
- --prefer-system
Use the system-wide node.js if nodejs or node is found in PATH, otherwise install the version given by --node. A found system node is used as is, its version is not checked against --node. Set prefer_system = True in ~/.nodeenvrc to make this the default. Ignored on Windows, where system-wide node.js is not supported.
- -l, --list
Lists available node.js versions.
- -p [VENV_DIR], --python-virtualenv [VENV_DIR]
Use the given python virtualenv, or the current one if no directory is given. Passing a directory is required when nodeenv lives in its own virtualenv (pipx, pipsi, uv tool) and the activated virtualenv doesn’t export VIRTUAL_ENV. Running it again with the same node version does not reinstall node; pass --force to reinstall.
- -r FILENAME, --requirements=FILENAME
Install all the packages listed in the given requirements file globally. May be given more than once.
- --local-requirements=FILENAME
Install all the packages listed in the given requirements file locally, into node_modules of the current directory. May be given more than once.
- --prompt=PROMPT
Provides an alternative prompt prefix for this environment.
- --force
Force installation in a pre-existing directory, and reinstall node even when the requested version is already installed.
- --update
Install npm packages from file without reinstalling node.
Installation options
- --prebuilt
Install node.js from prebuilt package (default).
- --source
Install node.js from the source (Unix only).
- --mirror=URL
Set mirror server of nodejs.org to download from. A file:// URL points nodeenv at a local directory instead of a server.
- -c, --clean-src
Remove “src” directory after installation. This is the default.
- --no-clean-src
Keep “src” directory after installation. With --source it holds the downloaded source tree, so a repeated --force build reuses it.
NPM options
- --npm=NPM_VER
The npm version to use, e.g., --npm=10.0.0. The default is the last available version (latest).
- --with-npm
Install npm into the new virtual environment. Required for node.js < 0.6.3. By default, the npm included with node.js is used.
- --no-npm-clean
Skip the npm 0.x cleanup. Cleanup is enabled by default.
- --isolate-npm
Keep npm’s cache (.npm), userconfig (.npmrc) and init-module (.npm-init.js) inside the environment instead of $HOME. Useful when $HOME is missing or read-only, or when the environment must not touch the user’s npm files. Settings from ~/.npmrc such as a private registry or auth tokens are then not seen inside the environment. Set isolate_npm = True in ~/.nodeenvrc to make this the default. Ignored on Windows.
Compilation options (Unix only)
- -j JOBS, --jobs=JOBS
Sets number of parallel commands at node.js compilation. The default is 2 jobs.
- --load-average=LOAD
Sets maximum load average for executing parallel commands at node.js compilation.
- -m MAKE_PATH, --make=MAKE_PATH
Path to make command.
- --without-ssl
Build node.js without SSL support.
- --debug
Build debug variant of the node.js.
- --profile
Enable profiling for node.js.
Other options
- -v, --verbose
Verbose mode.
- -q, --quiet
Quiet mode.
- -C CONFIG_FILE, --config-file=CONFIG_FILE
Load a different config file than ~/.nodeenvrc. Pass an empty string for no config (use built-in defaults).
- --ignore_ssl_certs
Ignore SSL certificates for package downloads. UNSAFE - use at your own risk.
- --with-certifi
Use the certifi certificate bundle for package downloads instead of the system certificate store. Useful when the system store is missing or outdated. If certifi is not installed, a warning is printed and the system store is used. Ignored when --ignore_ssl_certs is given. The same result can be achieved without this option by pointing SSL_CERT_FILE at the bundle:
$ SSL_CERT_FILE=$(python -c 'import certifi; print(certifi.where())') nodeenv env
- --version
Show program version and exit.
Configuration
You can use the INI-style file ~/.nodeenvrc to set default values for many options, the keys in that file are the long command-line option names.
These are the available options and their defaults:
[nodeenv] node = 'latest' npm = 'latest' with_npm = False jobs = '2' without_ssl = False debug = False profile = False make = 'make' prebuilt = True ignore_ssl_certs = False with_certifi = False mirror = None prefer_system = False isolate_npm = False clean_src = True
Alternatives
There are several alternatives that create isolated environments:
nave - Virtual Environments for Node. Nave stores all environments in one directory ~/.nave. Can create per node version environments using nave use envname versionname. Can not pass additional arguments into configure (for example –without-ssl) Can’t run on windows because it relies on a POSIX shell.
nvm - Node Version Manager. It is necessarily to do nvm sync for caching available node.js version. Can not pass additional arguments into configure (for example –without-ssl)
virtualenv - Virtual Python Environment builder. For python only.
LICENSE
BSD / LICENSE
Nodeenv changelog
Version 1.11.0
Fixed zsh source bin/activate aborting on the direct-call guard #398
Added check for how activate is called #384
Addressed the tarfile.extractall deprecation on Python >= 3.12 by setting filter='data', which also prevents writing files via “..” or absolute paths #380
Added support for Solaris/illumos #360
Added predeactivate hooks for Windows
Added error handling and tests for the node installation #336
Removed the leftover debug print that leaked a dict to stdout on every version detection #390
Added –with-certifi to download packages with the certifi certificate bundle #388
–node accepts npm-style semver ranges #393
Added –prefer-system to use system-wide node.js when available and install one otherwise #153
Added –isolate-npm to keep npm cache, userconfig and init-module inside the environment #154
Added tests that run the activation scripts in sh, dash, bash, zsh and fish.
-p no longer reinstalls node when the requested version is already in the virtualenv #159
Repeated -p runs no longer duplicate the predeactivate hook #159
-p accepts an optional virtualenv directory and prefers the activated VIRTUAL_ENV over the virtualenv nodeenv itself is installed in #156
-r/–requirements may now be given more than once, and the new –local-requirements installs the packages of a file locally, into “node_modules” of the current directory, which is what freeze -l writes. Under npm < 1.0.0, which has no -g, a local file is still installed the old way #206
The “src” directory is now removed after installation by default, which halves the size of an environment. Added –no-clean-src to keep it: with –source that is what lets a repeated –force build reuse the downloaded source tree #205
Documented that –mirror takes a file:// URL, so a local directory can serve as the download source #193
The posix activate is now written on Windows too, into “Scripts”, so git-bash and the other posix shells there can activate an environment #226
A download that reaches nothing at all, which a broken http_proxy or https_proxy usually causes, now reports the url and the proxy settings instead of a traceback #229
On Windows -p extends “activate.bat”, “deactivate.bat” and “Activate.ps1” of the python virtualenv instead of overwriting them, so VIRTUAL_ENV and the virtualenv’s own deactivation survive #243
A missing node.js archive now reports the urls that were tried and points at –list and –source instead of a traceback #250
freeze now reads npm ls –parseable instead of the drawn tree: scoped packages keep their scope, a package whose name contains “npm” is no longer dropped, and npm and corepack, which come with node.js itself, are left out of the list. The fish version, which printed nothing at all under npm >= 1, now writes the same file as the posix one #287
musl is now detected whatever the vendor field of the host triplet says, so Alpine’s own python3 (x86_64-alpine-linux-musl) gets the musl build of node.js instead of the glibc one #290
On Windows “nodejs.exe” is linked with os.symlink, falling back to a hard link, instead of mklink, which broke on paths with forward slashes or spaces and needs elevation or Developer Mode. If both fail, only a warning is logged #303
Version 1.10.0
Added support for Python 3.13 #367
Added support for UV virtual environments #386
Used sh instead of bash #389
Replaced the remaining which(1) calls with shutil.which() #355
Supported a leading v in .node-version #359
Checked the host platform when finding the node version #363
Fixed archmap lookup to be lowercase #382
Version 1.9.1
Version 1.9.0
Switched to packaging for version comparison #338 and then dropped the dependency in favor of a simple version-parsing function #352
Fixed GitHub Actions #347
Added Python 3.11 and 3.12 test coverage #348
Added support for shells with “set -u” #345
Replaced pipes.quote with shlex.quote on Python 3.3+ #342
Removed usage of the non-portable which #346
Version 1.8.0
Fixed the function name in fish_prompt #312
Added support for riscv64 #313
Upgraded GitHub Actions #317
Made the mock dependency optional #320
GitHub Actions: fail-fast: false #327
Made multiple attempts to download the node.js archive (IncompleteRead error) #329
Logged the URL on download failures #330
Version 1.7.0
Dropped python3.4, python3.5 and python3.6
Supported python releases before 3.7 in tests #272
Required setuptools in setup.py #289
Used the version specified in .node-version if it exists #288
Fixed the problem when used with fish and virtualenv #294
Replaced optparse with argparse #295
Set the SSL protocol when ssl certs are ignored #296
Fixed tests, tested Python 3.10 and moved tests to GitHub Actions #298
Patched node installation for M1 #299
Added ability to configure the mirror through the settings file #307
Added –with-npm to README #308
Version 1.6.0
Tested for nodejs or node in tests #270
Removed the main node.js mirror in tests if musl #271
Fixed the nodeenv prompt when using Fish #273
Used node instead of nodejs #275
Fixed typo, remaning -> remaining #276
Resolved the venv dir for Fish #277
Added support for installing the latest LTS release #281
Created a broad mapping for M1 #282
Version 1.5.0
Version 1.4.0
Switched to /download/release/index.json to discover versions
Dropped io.js support
Worked around IncompleteRead when downloading src #258
Fixed erasing of NODE_VIRTUAL_ENV while deactivate_node in fish #255
Accepted a URL as well as a domain name for the –mirror argument #252
Downloaded musl-compatible node from unofficial-builds #247
Version 1.3.5
Fixed error 183 (“already exists”) on Windows when installing prebuilt node #249
Version 1.3.4
Used the prebuilt windows zip which contains npm #230
Fixed url in the CHANGES file #231
Fixed escape sequences #232
Fixed npm_url in install_npm_win #233
Changed the URL for downloading npm in Cygwin #234
Fixed nodeenv in case python4 is ever a thing #241
Produced py2.py3 wheels, nodeenv is a pure python package #242
Printed a blank line when install_node fails #236
Added an option to set your own mirror #208
Fixed CI (flake8 errors) #245
Fixed call to logger.info(…) #246
Version 1.3.3
Installed a certain npm version via npm install #225
Version 1.3.2
Version 1.3.1
Version 1.3.0
Version 1.2.0
Version 1.1.4
Fixed directory copy #188
Version 1.1.3
Fixed spaces in paths #187
Version 1.1.2
Fixed MANIFEST.in #184
Version 1.1.1
Version 1.1.0
Windows support
Version 1.0.0
Version 0.13.6
Use https for nodejs.org. See # 129
Version 0.13.5
Improved user-agent identification
Version 0.13.4
Version 0.13.3
Version 0.13.2
Fixed freeze command. See # 121
Version 0.13.1
Version 0.13.0
Version 0.12.3
Fixed check for installed curl/tar/etc for py3.
Version 0.12.2
Version 0.12.1
Version 0.12.0
Added support for io.js (new option --iojs)
Fixed get_last_stable_node_version for python3
Version 0.11.1
Version 0.11.0
Version 0.10.0
Version 0.9.6
Version 0.9.5
Fixed a few spelling typos in README. See # 74
Fixed example of using –update option in README. See # 74
Improved args passing into shim script. See # 75
Try to find nodejs if used system-wide node as well. See # 76
Added assert if used system-wide node and it wasnt found. See # 76
Added -l option into freeze command. See # 71
Version 0.9.4
Fixed support for python2.6. See # 70
Version 0.9.3
Version 0.9.2
Fixed infinite loop when system-wide node used. See # 67
Version 0.9.1
Fixed ‘shim’ script if used system-wide node
Fixed shebang in the ‘shim’
Added shim with name ‘node’ in case of using system-wide node
Version 0.9.0
Added shim script. See # 59
Version 0.8.2
Version 0.8.1
Fixed system’s node usage. See # 62
Version 0.8.0
Version 0.7.3
Version 0.7.2
Bug fixing in freeze. See # 47
Version 0.7.1
Added --make option
Version 0.7.0
Version 0.6.6
Version 0.6.5
Node’s source not loaded if it already exists in FS.
Version 0.6.4
Added python3 compatibility. See # 32
Version 0.6.3
Fixed nodeenv -p. See issue # 31
Version 0.6.2
Version 0.6.1
Used pkg_resources.parse_version to compare versions. See pull # 29
Fixed doubling prompt inside a virtualenv. See issues # 26
Version 0.6.0
Version 0.5.3
Bug fix. Used https, /dist/latest/. See pull # 16
Version 0.5.2
Improved installation logic for release candidate versions. See pull # 10
Version 0.5.1
Improved logic for the option ‘–without-npm’. See issue # 14, pull # 15
Version 0.5.0
The virtual environment’s path is no longer hardcoded into the activation script. See pull # 13
Version 0.4.3
Fixed metavar for --npm
npm install -g used for npm >=1.0, not noly for latest
Version 0.4.2
Added README.ru.rst
Version 0.4.1
Fixed bug in print_node_versions. See pull # 11
Added deps in README
Version 0.4.0
Version 0.3.10
Fixed bug in url detection for node.js download
Version 0.3.9
Version 0.3.8
Added NODE_PATH variable export (for correct module search after installation via npm)
Version 0.3.7
Shows command output when error occurs
Excluded ‘npm’ from freeze list
Fixed bug with ‘not only letter’ names in freeze list
Added global installation for npm >= 1.0 (when install soft from requirement file)
Version 0.3.6
Fixed freeze output command. See request # 5
Diagnostic message fixed. See pull # 4
Version 0.3.5
Added option --npm to install certain npm.js version. Request .
Fixed freeze command for npm >= 1.0.x.
Version 0.3.4
Fixed problem #2 with new npm installation script. Added --no-npm-clean option. The default to the npm 0.x cleanup.
Version 0.3.3
Fixed problem #1 with installation from PyPI via easy_install. Added MANIFEST.in file.
Version 0.3.2
Internal improvements
Logging refactoring
Version 0.3.1
Default environment promt is folder name
Version 0.3.0
Renamed nve to nodeenv
Metadata
Release files for nodeenv 1.11.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| nodeenv-1.11.0.tar.gz | 99.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| nodeenv-1.11.0-py2.py3-none-any.whl | Python 3, Python 2 | none | any | Details |
Total release size: 133.6 kB
Release files / nodeenv-1.11.0.tar.gz
| Download URL | nodeenv-1.11.0.tar.gz |
|---|---|
| Size | 99.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3ce8fe5b71d16e8af7039ca65257354100bc772965d6bc549070649e53b1b146
|
|
BLAKE2b-256 checksum How to use checksums |
9a8e105de02c1322cfada6d9710d9146ef8026419d433c9d08359a2d35805811
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|
Release files / nodeenv-1.11.0-py2.py3-none-any.whl
| Download URL | nodeenv-1.11.0-py2.py3-none-any.whl |
|---|---|
| Size | 34.3 kB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
edaa16e6c14d7cf395d75d4bbd5a26390f4dc06501a33b4e76282b02cc688a25
|
|
BLAKE2b-256 checksum How to use checksums |
54c812811c9b48fde162bb72b6f2e78fada9a247a09d7bb5be2050a5d099c77b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.6
|