nvenv

nvenv

Python venv-like Node.js environment manager - Create project-local Node.js installations without global environment pollution.

Overview

nvenv is a Node.js environment management tool inspired by Python's venv. It follows the Gradle philosophy of project-local installations, ensuring that each project has its own isolated Node.js environment without polluting the global system.

Key Features

• Project-local installation: Each environment is completely isolated
• No global pollution: Node.js binaries are downloaded and stored within the project
• Python venv-like interface: Familiar activate/deactivate workflow
• Zero dependencies: Uses only Node.js standard library
• Cross-platform: Supports macOS, Linux, and Windows
• npx-ready: No global installation required

Philosophy

Unlike tools like nvm, asdf, or mise that manage Node.js versions globally, nvenv takes a Gradle-like approach where each project has its own local Node.js installation. This eliminates version conflicts between projects and ensures complete environment isolation.

Installation

No installation required! Use directly with npx:

npx nvenv --node=18.20.0 venv

Or install globally if you prefer:

npm install -g nvenv
nvenv --node=18.20.0 venv

Usage

Creating a New Environment

Create a new Node.js environment with a specific version:

npx nvenv --node=18.20.0 venv

This will:

• Download Node.js v18.20.0 for your platform
• Extract it to venv/lib/
• Create symlinks in venv/bin/
• Generate activation scripts

Activating the Environment

Bash/Zsh:

source venv/bin/activate

Fish:

source venv/bin/activate.fish

After activation, your shell prompt will show (nvenv) prefix, and node, npm, and npx commands will use the local installation.

Using the Environment

Once activated, use Node.js and npm as usual:

(nvenv) $ node --version
v18.20.0

(nvenv) $ npm install express
(nvenv) $ node app.js

Deactivating the Environment

To return to your system's Node.js:

(nvenv) $ deactivate

Directory Structure

After creating an environment, you'll have:

venv/
├── .nvenv                 # Metadata (version, platform, arch)
├── bin/
│   ├── activate          # Bash/Zsh activation script
│   ├── activate.fish     # Fish activation script
│   ├── node              # Symlink to Node.js binary
│   ├── npm               # Symlink to npm
│   └── npx               # Symlink to npx
└── lib/
    └── node-v18.20.0/    # Full Node.js installation

Examples

Create environment with specific Node.js version

# Node.js 18.x
npx nvenv --node=18.20.0 venv

# Node.js 20.x
npx nvenv --node=20.11.0 my-project

# Latest LTS
npx nvenv --node=20.18.0 production

Use in CI/CD

# GitHub Actions example
- name: Create Node.js environment
  run: npx nvenv --node=18.20.0 venv

- name: Install dependencies
  run: |
    source venv/bin/activate
    npm install
    npm test

Multiple projects with different Node.js versions

# Project A uses Node.js 16
cd project-a
npx nvenv --node=16.20.0 venv
source venv/bin/activate
npm install

# Project B uses Node.js 20
cd ../project-b
npx nvenv --node=20.11.0 venv
source venv/bin/activate
npm install

Configuration

Environment Variables

nvenv can be configured using environment variables:

• NVENV_SILENT: Set to 1 to suppress progress output during environment creation
• NVENV_MIRROR: Custom mirror URL for Node.js downloads (default: https://nodejs.org/dist)

Using a Custom Mirror

For faster downloads in certain regions, you can use a mirror:

# China mirror (npmmirror/Taobao)
export NVENV_MIRROR=https://npmmirror.com/mirrors/node
npx nvenv --node=18.20.0 venv

# Or set for a single command
NVENV_MIRROR=https://npmmirror.com/mirrors/node npx nvenv --node=18.20.0 venv

Popular mirrors:

• China (npmmirror): https://npmmirror.com/mirrors/node
• China (Tencent): https://mirrors.cloud.tencent.com/nodejs-release
• Europe: Check regional mirrors based on your location

Silent Mode

Suppress verbose download progress output:

# Silent mode for CI/CD
NVENV_SILENT=1 npx nvenv --node=18.20.0 venv

# Or use the --silent flag
npx nvenv --silent --node=18.20.0 venv

Comparison with Other Tools

Feature	nvenv	nvm	asdf	mise	volta
Project-local	✓	✗	✗	✗	✗
No global state	✓	✗	✗	✗	✗
Zero config	✓	✗	✗	✗	✗
npx-ready	✓	✗	✗	✗	✗
Python venv-like	✓	✗	✗	✗	✗

Why nvenv?

Traditional Node.js version managers like nvm or asdf manage versions globally and share them across projects. This can lead to:

• Version conflicts: Different projects requiring different Node.js versions
• Environment pollution: Global node_modules affecting multiple projects
• Reproducibility issues: Hard to ensure exact same environment across machines

nvenv solves these by giving each project its own isolated Node.js installation, similar to how Gradle downloads dependencies per-project or how Python's venv creates isolated Python environments.

Supported Platforms

• macOS: arm64, x64
• Linux: x64, arm64
• Windows: x64 (experimental)

Development

# Clone the repository
git clone https://github.com/yourusername/nvenv.git
cd nvenv

# Test locally
node src/cli.js --node=18.20.0 test-env

# Activate test environment
source test-env/bin/activate

FAQ

Should I commit the venv directory to git?

No. Add it to .gitignore:

venv/

Users should create their own environment using npx nvenv.

Can I use this with existing projects?

Yes! Just create a new environment in your project directory:

cd my-existing-project
npx nvenv --node=18.20.0 venv
source venv/bin/activate
npm install

How much disk space does each environment use?

Approximately 40-60MB per environment, depending on the Node.js version and platform. This is the trade-off for complete isolation.

License

MIT

Inspiration

• Python's venv - Virtual environment concept
• Gradle - Project-local dependency management
• nodeenv - Python-based Node.js environment tool

Contributing

Contributions welcome! Please open an issue or PR on GitHub.

Author

Created as a weekend project inspired by the desire for Gradle-like Node.js environment management.