How to Use npm on Ubuntu: Installation, Basic Commands, and Troubleshooting Guide

1. Introduction

Why Use npm on Ubuntu

One of the essential tools for both frontend and backend development is npm (Node Package Manager). npm is widely used as the package management tool for Node.js, allowing developers to easily install and manage JavaScript libraries and tools.

By using npm on Ubuntu, you can take advantage of Linux’s lightweight performance and flexible package management while significantly improving development efficiency. Ubuntu is a distribution supported by a large developer community and is widely used for everything from server operations to local development environments.

In particular, when working with Node.js-based frameworks such as Vue.js, React, and Next.js, managing packages with npm is the standard approach. Setting up these tools on Ubuntu allows you to build a stable development environment with fewer issues compared to Windows or macOS.

Purpose of This Article

This article provides a step-by-step guide to installing npm on Ubuntu and mastering its basic usage. It is especially intended for the following audiences:

• Developers who are new to Ubuntu
• Those struggling with Node.js or npm setup
• Anyone who wants to learn npm in a structured way

Multiple installation methods are introduced, along with their features, advantages, and disadvantages. In addition, this guide covers common errors, troubleshooting tips, and useful commands to help readers use npm smoothly on Ubuntu.

2. Installing Node.js and npm on Ubuntu

To use npm on Ubuntu, you must first install Node.js. Since npm is bundled with Node.js, installing Node.js automatically makes npm available.

Here are three major methods for installing Node.js and npm on Ubuntu. Each method has its own characteristics, so it is important to choose the one that best suits your development style and purpose.

Method 1: Using the Official Ubuntu Repository

Steps

Node.js is available in Ubuntu’s standard repositories. This is the simplest and most beginner-friendly approach.

sudo apt update
sudo apt install nodejs npm

After installation, you can check the versions with the following commands:

node -v
npm -v

Advantages

• Simple commands that are easy to understand
• Stable versions provided by Ubuntu

Disadvantages

• The Node.js and npm versions are often outdated, so the latest features may not be available

Method 2: Using the NodeSource PPA

By using the NodeSource repository, which closely follows official Node.js support, you can install newer versions of Node.js and npm.

Steps (Example: Installing Node.js 18.x)

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install -y nodejs

npm is automatically installed together with Node.js.

Advantages

• Access to relatively new and stable versions
• Easy installation with good Ubuntu compatibility

Disadvantages

• As with other PPAs, dependency management may be required

Method 3: Using nvm (Node Version Manager)

If you want to switch between multiple Node.js versions, using nvm is the most flexible and powerful option.

Steps

First, install nvm:

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

Then reload your shell and install Node.js using nvm:

source ~/.bashrc  # or ~/.zshrc
nvm install 18
nvm use 18

npm is automatically installed along with Node.js.

Advantages

• Freely switch between Node.js versions
• Set appropriate versions per project
• Safe, as it does not affect the system globally

Disadvantages

• Slightly more complex setup compared to other methods
• Requires editing shell configuration files

Which Method Should You Choose?

In general, nvm is the most recommended option for long-term npm development on Ubuntu. However, if you want a quick and simple setup, using the NodeSource PPA is also a solid choice.

3. Basic npm Usage

Once Node.js and npm are installed on Ubuntu, you can start managing packages with npm. npm is a powerful tool for installing, updating, and removing JavaScript packages.

This section introduces commonly used npm commands and basic operations.

Installing Packages

Local Installation

Packages used only within a specific project should be installed locally. This is the standard approach. Packages are installed in the node_modules directory and recorded in package.json.

npm install package-name

Example: Installing axios

npm install axios

Only scripts within the same project can use locally installed packages.

Global Installation

Tools used system-wide, such as CLI utilities, should be installed globally.

npm install -g package-name

Example: Installing http-server globally

sudo npm install -g http-server

On Ubuntu, using -g may require sudo.

Uninstalling Packages

Removing Local Packages

npm uninstall package-name

Removing Global Packages

sudo npm uninstall -g package-name

Updating Packages

Updating a Specific Package

npm update package-name

Updating All Dependencies

npm update

Updates are applied within the version ranges specified in package.json, so pay attention to version constraints.

Installing Development Dependencies (–save-dev)

Development-only packages such as testing or build tools should be installed using the --save-dev option.

npm install --save-dev package-name

Example: Installing jest as a development dependency

npm install --save-dev jest

This records the package under devDependencies in package.json.

Listing Installed Packages

List Local Packages

npm list

List Global Packages

npm list -g --depth=0

Using --depth=0 shows only top-level packages, making the output easier to read.

Managing Dependencies with package.json

The package.json file is a core component of npm-based projects. It records package names, versions, scripts, and overall project configuration.

You can create it using:

npm init

For a simplified setup with default values:

npm init -y

4. Common Problems and Solutions

When using npm on Ubuntu, you may encounter errors or unexpected behavior. This section introduces common issues and how to resolve them.

Permission Errors

Symptom

EACCES: permission denied

Cause

This occurs when the current user does not have write permission for the directory where npm is trying to install packages. On Ubuntu, writing to system directories such as /usr/lib/node_modules requires sudo.

Solution

• Run with sudo:

sudo npm install -g package-name

• Or change the global installation directory to a user-owned path:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

Add the following to ~/.bashrc or ~/.profile:

export PATH="$HOME/.npm-global/bin:$PATH"

Apply the changes:

source ~/.bashrc

npm Command Not Found

Symptom

command not found: npm

Cause

• Node.js or npm installation failed
• PATH environment variable is not configured

Solution

Check the path:

which npm

If nothing is returned, reinstall or verify PATH settings. If using nvm, ensure the initialization code exists in your shell configuration file:

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

Package Installation Failures or Version Conflicts

Symptoms

• Version conflicts when installing a package
• Numerous warnings during npm install

Solutions

npm install package-name@latest

npm ls package-name

npm install --legacy-peer-deps

rm -rf node_modules package-lock.json
npm install

Useful Debugging Commands

• npm doctor

npm doctor

• npm audit

npm audit
npm audit fix

5. Frequently Asked Questions (FAQ)

Q1. How can I update npm to the latest version on Ubuntu?

A1.

sudo npm install -g npm@latest

If you are using nvm, sudo is not required.

Q2. What is the difference between global and local installation?

A2.

• Local Installation: Project-specific dependencies stored in node_modules
• Global Installation: System-wide CLI tools, often requiring sudo

Q3. What are the benefits of using nvm?

A3.

nvm allows you to switch between multiple Node.js versions safely and efficiently, making it ideal for multi-project development.

Q4. What should I do if npm dependencies break?

A4.

rm -rf node_modules package-lock.json
npm install

Q5. Are npm WARN and audit messages a problem?

A5.

Warnings are not fatal but indicate potential issues. For security-related warnings, you can try:

npm audit fix

Q6. What can I build with npm on Ubuntu?

A6.

• Frontend frameworks (React, Vue, Svelte)
• Static site generators (Next.js, Nuxt)
• Backend applications (Express, NestJS)
• CLI tools
• Testing environments

6. Conclusion: Master npm on Ubuntu

This article covered the essentials of installing and using npm on Ubuntu, from setup to troubleshooting.

The most important step is to experiment hands-on. By running commands and understanding error messages, you will steadily deepen your skills as a developer.

This concludes the complete guide to using npm on Ubuntu. We hope it helps you build a more efficient and powerful development environment.