Effortless Node.js Installation on Ubuntu: Practical Steps for Reliable Development

Node.js sits at the core of countless production backends, CLI tooling, and CI/CD pipelines. On Ubuntu, a misconfigured or out-of-date Node.js deployment introduces friction—dependency hell, build failures, CI regressions. Correct installation is not just convenience; it’s insurance against future incompatibility.

Below, a straightforward installation flow, designed for repeatability across dev, CI, or container images. No legacy repo ambiguity, minimum manual clean-up.

Why Default Ubuntu Node.js Packages Are Insufficient

Developers routinely hit version drift:
apt install nodejs yields a stale release (often 12.x or 14.x, depending on LTS cycles), incompatible with modern packages (think: Prisma, Next.js, modern ESM-only modules). You’ll see errors like:

npm ERR! code EBADENGINE
npm ERR! notsup Unsupported engine for package: wanted: {"node":">=20.0.0"} (current: "node@14.21.3")

Solution: Do not rely on Ubuntu main for Node.js. Instead, use the NodeSource repository or NVM for precise version control.

1. Update System Packages

Critical at the outset—outdated core libraries or an unpatched apt database trigger silent build failures downstream.

sudo apt update && sudo apt upgrade -y

2. Ensure curl Is Available

Most installation scripts rely on curl. Test presence:

curl --version

Not installed?

sudo apt install curl -y

3. Add NodeSource: Canonical Node.js for Ubuntu

NodeSource tracks LTS and even/nightly branches for production stability.

Install Node.js 20.x (current LTS as of June 2024):

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

Side note: NodeSource provides scripts for prior major versions (e.g., 18.x, 16.x) if you’re pinning legacy workloads.

4. Install Node.js and npm

sudo apt-get install -y nodejs

This pulls both node and the corresponding npm version, mapped to the selected major.
No need to install npm separately.

5. Validate Installation

Confirm binaries are on $PATH:

node -v
npm -v

Typical output:

v20.12.2
10.7.0

If either binary is missing, re-check /usr/bin/ and review apt logs.

6. Native Module Compilation Support (Recommended)

Many npm dependencies (e.g., bcrypt, sharp, sqlite3) require native bindings at install. Missing build tools = cryptic error logs.

sudo apt-get install -y build-essential

Error example, if omitted:

gyp ERR! find Python Python is not set from command line or npm configuration

7. Alternative: Use nvm for Multi-Version Management

Managing a suite of legacy and modern projects? System-wide Node.js is limiting. NVM enables per-shell versioning, instant rollback, and disposable test environments. It doesn’t require sudo.

Install nvm (v0.39.5, stable June 2024):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash

Load directly into current shell:

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

Install latest LTS Node.js:

nvm install --lts
nvm use --lts

Switch versions per-project:

nvm install 18
nvm use 18

Note: Project-specific .nvmrc files are a best practice for team/workflow parity.

Practical Example: CI Containerfile (Docker)

For consistent CI or ephemeral build environments:

FROM ubuntu:22.04
RUN apt-get update && apt-get install -y curl build-essential \
 && curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
 && apt-get install -y nodejs

This pattern avoids interactive prompts and is reproducible across runners.

Non-Obvious Tip

• If you see multiple node or npm paths (e.g., /usr/bin/node, /usr/local/bin/node), check for global installs or ancient manual builds in /usr/local/. Clean up with:

  sudo rm -rf /usr/local/bin/node /usr/local/bin/npm
  

• For CI, pin exact Node.js and npm versions to avoid build surprises from upstream changes.

Summary Table

Command Recap

sudo apt update && sudo apt upgrade -y
sudo apt install curl build-essential -y
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
node -v
npm -v

Or, for multi-version workflows:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
nvm install --lts
nvm use --lts
node -v

Known Issue:
Some legacy npm scripts expect the binary as nodejs, not node. If you hit env: node: No such file or directory, create a symlink:

sudo ln -s /usr/bin/node /usr/bin/nodejs

That’s the practical route to a stable, modern Node.js stack on Ubuntu—no dependency drift, no permission headaches. If edge-case issues arise (broken dpkg, networking errors from NodeSource, cross-compilation), double-check upstream notices or fall back to nvm. This isn’t perfect, but it covers production and dev needs for 95% of scenarios.