npm install downloads and sets up the packages your project needs

npm install is a command that reads your project's dependency list and downloads all the code your project requires to run. When you type npm install in your project folder, npm looks at a file called package.json, finds every package listed there, downloads each one from the npm registry, and stores them in a folder called node_modules. It also creates or updates a package-lock.json file that locks each package to the exact version you installed, so the same versions install on every machine that runs the command.

You run this command when you first clone a project from GitHub, when you add a new package to your project, or when you switch to a different branch that has different dependencies. Without running npm install, your project folder will not have the code it needs to run.

Key Takeaways

  • npm install reads package.json, downloads all listed packages from the npm registry, and stores them in node_modules.
  • The command creates or updates package-lock.json to record the exact version of each package, ensuring consistency across machines.
  • npm install package-name adds a new package to your project and updates both package.json and package-lock.json.
  • You must run npm install after cloning a project, switching branches, or pulling changes that modified dependencies.

What happens when you run npm install

When you type npm install in your terminal, npm performs several steps in order. First, it reads the package.json file in your current folder to see what packages your project depends on. Then it connects to the npm registry (a central server that stores all published packages) and downloads each package listed in package.json. Each package may itself depend on other packages, so npm downloads those too — this is called the dependency tree.

All downloaded packages land in a folder called node_modules inside your project. npm also creates or updates a file called package-lock.json that records the exact version number of every package installed, including all the nested dependencies. This file ensures that if someone else runs npm install on the same project, they get the exact same versions you have.

The whole process usually takes a few seconds to a few minutes, depending on how many packages your project needs and how fast your internet connection is.

The difference between npm install and npm install package-name

Running npm install with no package name installs everything listed in package.json. Running npm install package-name (for example, npm install express) does something different: it downloads that specific package, adds it to your package.json file under the dependencies section, and updates package-lock.json.

You use npm install package-name when you want to add a new package to a project you are actively working on. You use npm install alone when you are setting up a project for the first time, or when you have pulled changes from a teammate that modified the dependencies.

Why package-lock.json matters

Without package-lock.json, two developers running npm install on the same project might end up with different package versions. This happens because package.json often lists version ranges (like "express": "^4.18.0") rather than exact versions. The caret symbol means npm can install any version from 4.18.0 up to (but not including) 5.0.0. If version 4.19.0 is released between when you install and when your teammate installs, they might get a different version than you.

package-lock.json solves this by recording the exact version of every package that was installed. When npm sees this file, it ignores the version ranges in package.json and installs the exact versions listed in the lock file instead. This is why you should always commit package-lock.json to your version control system (like Git) alongside package.json.

What to do if npm install fails

If npm install stops with an error, the most common causes are a network problem, a corrupted node_modules folder, or an outdated version of npm itself. Start by checking your internet connection and trying again. If that does not work, delete the node_modules folder and the package-lock.json file, then run npm install again. This forces npm to download everything fresh.

If the error persists, update npm by running npm install -g npm@latest (the -g flag installs it globally on your machine rather than in your project). Then try npm install again. If you still see an error message, read it carefully — it usually tells you which package is causing the problem and why.

npm install vs npm ci

A related command called npm ci (short for "clean install") is similar to npm install but stricter. npm ci requires that package-lock.json already exists, and it installs the exact versions from that file without updating it. npm install, by contrast, can update package-lock.json if the versions in package.json have changed.

Most developers use npm install for everyday work. Teams use npm ci in automated environments like continuous integration servers, where you want to may provide that the same versions install every time without any surprises.

Frequently Asked Questions

Do I need to run npm install every time I open my project?

No. You only need to run it once after cloning a project, when you switch to a branch with different dependencies, or when you pull changes that modified package.json. After that, the node_modules folder stays on your machine and your project works normally.

What is the node_modules folder and why is it so large?

The node_modules folder contains all the code for every package your project depends on, plus all their dependencies. A single package might depend on dozens of other packages, so the folder grows quickly and can easily reach hundreds of megabytes or even gigabytes. This is normal. You should add node_modules to your .gitignore file so it does not get committed to version control.

Can I use npm install offline?

Not on the first run — npm needs to download packages from the registry. However, once packages are downloaded and stored in node_modules, you can work offline. If you need to install on a machine without internet access, you can copy the node_modules folder from another machine, though this is not recommended because different operating systems may require different compiled versions of some packages.

What does the --save flag do?

The --save flag (used as npm install package-name --save) adds the package to your package.json file. Modern versions of npm do this by default, so you do not need to type --save anymore — npm install package-name alone adds it to package.json.