What npm does and why you use it to install

npm is a package manager — a tool that downloads and installs code libraries that other people have written, then puts them in the right place so your project can use them. When you write JavaScript, you often need functionality that someone else has already built: a date formatter, a color converter, a way to make HTTP requests. Instead of writing that code yourself, you install it with npm and import it into your project.

npm comes bundled with Node.js, so if you have Node.js installed on your computer, you already have npm. You use it from the command line — the terminal on Mac or Linux, or Command Prompt or PowerShell on Windows. When you run an npm command, it reads your project's configuration file, downloads the package from npm's central repository, and stores it in a folder called node_modules.

Key Takeaways

  • npm is installed automatically when you install Node.js, and you run it from your terminal or command prompt.
  • The command npm install package-name downloads a package and saves it to your project's node_modules folder and package.json file.
  • Your project's package.json file tracks which packages you need and which versions, so other people can install the same packages by running npm install with no package name.
  • Local packages go in node_modules and are used only by your project; global packages are installed once on your computer and can be used from anywhere.
  • Running npm install in a folder with an existing package.json downloads all the packages listed there, which is how you set up a project someone else started.

Installing a single package into your project

Open your terminal or command prompt and navigate to your project folder. If you do not have a package.json file yet, create one by running npm init and answering the prompts, or run npm init -y to accept all defaults. The package.json file is how npm tracks what your project needs.

Once you have a package.json, install a package by typing npm install package-name. For example, to install a package called lodash, you would run:

npm install lodash

npm downloads the package and all its dependencies — the other packages it needs to work — and stores them in a folder called node_modules. It also updates your package.json file to record that your project uses lodash. When you open package.json, you will see lodash listed under "dependencies" with a version number.

The first time you install packages, npm also creates a file called package-lock.json. This file locks the exact versions of every package and dependency, so that if someone else installs your project later, they get the same versions you have. Do not edit this file by hand — npm manages it automatically.

Installing all packages from an existing package.json

If you download a project that someone else wrote, or if you clone a repository from GitHub, the folder will contain a package.json file but no node_modules folder. The node_modules folder is not usually stored in version control because it is large and can be recreated from package.json.

To set up the project, navigate to the project folder in your terminal and run:

npm install

With no package name, npm reads package.json and installs every package listed there, using the exact versions recorded in package-lock.json. This ensures your environment matches the original developer's environment.

The difference between local and global packages

By default, npm install package-name installs a package locally — into your project's node_modules folder. Local packages are used only by that project. You import them in your code with import or require.

Some packages are tools you run from the command line rather than code you import. Examples include create-react-app, which generates a new React project, or http-server, which starts a simple web server. These are often installed globally so you can run them from anywhere on your computer. To install globally, add the -g flag:

npm install -g http-server

Global packages are stored in a system folder, not in your project. You can then run http-server from any terminal window in any folder. Most of the time, you will install packages locally. Install globally only when the package documentation tells you to, or when you want a command-line tool available everywhere.

Using installed packages in your code

Once a package is installed locally, you import it into your JavaScript file. The exact syntax depends on whether the package uses ES6 modules or CommonJS, but the most common pattern in modern JavaScript is:

import lodash from 'lodash';

Node.js looks for the package name in node_modules and loads it. You can then use the functions or objects that package exports. For lodash, you might write:

const numbers = [3, 1, 4, 1, 5];const sorted = lodash.sortBy(numbers);

Each package's documentation shows what functions it provides and how to use them. The package.json file and node_modules folder stay on your computer; when you run your code, Node.js finds the packages automatically.

Updating and removing packages

To update a package to a newer version, run npm update package-name. npm checks for newer versions that match the version range in your package.json and installs the latest one that fits. If you want to update all packages at once, run npm update with no package name.

To remove a package you no longer need, run npm uninstall package-name. This deletes it from node_modules and removes it from package.json. If you want to keep the package listed in package.json but just remove it from node_modules temporarily, run npm prune, which removes any packages in node_modules that are not listed in package.json.

Frequently Asked Questions

Do I need to commit node_modules to version control?

No. Add node_modules to your .gitignore file so it is not stored in Git. Other people can recreate it by running npm install after cloning your repository. This keeps your repository small and avoids merge conflicts when different people install different versions.

What does the caret and tilde mean in package.json versions?

A caret (^) before a version number, like ^1.2.3, means npm can install any version up to the next major version. A tilde (~) means npm can install any patch version. These ranges let npm install security updates automatically while preventing breaking changes. You can also specify an exact version with no symbol.

Why do I get an error that a package is not found?

The most common reason is that you have not run npm install yet, so node_modules does not exist. Run npm install or npm install package-name to download it. If the error persists, check that you spelled the package name correctly and that it exists on npm's registry.

Can I install a specific version of a package?

Yes. Run npm install package-name@version-number. For example, npm install lodash@4.17.21 installs that exact version. You can also use version ranges like npm install lodash@">=4.17.0 <5" to install any version in that range.