npm install | how it works

If you're new to npm, start here...

npm install downloads a package and its dependencies.

npm install can be run with or without arguments.

When run without arguments, npm install downloads dependencies defined in a package.json file and generates a node_modules folder with the installed modules.

When run with arguments, npm install downloads specific modules to the node_modules folder.

The package.json file dictates what modules will get installed in the node_modules folder. It's important that npm install is run in the same location as the package.json file.

Let's look at some updated examples...

Key Takeaways

• npm install without arguments installs all dependencies from package.json.
• Use specific arguments to install individual packages or multiple packages in one go.
• The package-lock.json file ensures consistency by locking dependency versions.
• npm install can install globally with the --global flag.
• devDependencies are excluded when using the --production flag.

npm install (no arguments)

npm install
npm i

Both of these commands do the same thing. Running npm install without arguments installs modules defined in the dependencies section of the package.json file.

It's crucial that npm install is run in the same directory as the package.json file.

The downloaded modules are placed in a node_modules folder in the same location as package.json.

npm install also generates a package-lock.json file. This file describes the exact dependency tree that was installed. As of npm 9, the lock file is aligned more closely with package manager workflows to ensure deterministic builds.

npm dependency resolution

So how does npm resolve which versions to install? This is particularly relevant when different packages require different versions of the same module.

Consider that module A requires v1 of module C, while module B requires v2. npm's mechanism resolves both by placing one version directly and another as a nested dependency to respect compatibility.

npm will handle conflicts by hoisting, flattening, and deduping dependencies wherever possible to reduce bloat and prevent version conflicts.

npm install (with arguments)

npm install can be run with different arguments. Here are some of the more important ones to be aware of...

npm install (specified package)

npm install express

When npm install is run with a specified package argument, it installs the package in the existing node_modules directory.

You can optionally provide a specific version as well...

npm install express@latest

When a version is not provided, npm automatically downloads the latest stable version.

You can also specify several packages in the same command...

npm install express eslint mongo

This will install express, eslint, and mongo in a single command.

npm install (from git)

npm install git+https://github.com/user/repo.git

You can install packages directly from a Git repository. This is useful for pulling in a specific version or branch that may not yet be published to npm.

npm install (with options)

In addition to arguments, npm install can be run with different options. Here are some of the more important ones to be aware of...

npm install (with --global)

npm install -g
npm install --global

When run with --global or -g, npm install installs the package globally. This sidesteps the package.json and installs the package in a shared system location, making it available to all projects.

npm install (with --save)

As of npm 7, the --save flag is no longer necessary because npm now automatically adds installed packages to package.json by default.

npm install (with --save-dev)

The --save-dev flag adds the package to the devDependencies section of package.json.

npm dependencies vs devDependencies

So what's the difference? Packages included as devDependencies won't get installed when the optional --production flag is used. This makes it possible to exclude packages you only need for development.

For example, tools like Webpack and Babel are typically included as devDependencies because they're necessary during development and build processes but not in the production runtime environment.

npm install (with --production)

npm install -p
npm install --production

The --production flag ensures that only dependencies are installed, excluding devDependencies, thus reducing the final bundle size for deployment.

FAQ

What happens if I don't have a package-lock.json file?

Without a package-lock.json, subsequent installs might yield different dependency trees due to updates in the packages. The lock file ensures consistency.

How do I specify a package version?

You can specify a version by appending it to the package name like so: npm install package@version.

Why should I use --save-dev?

Use --save-dev for packages only needed during development, such as testing or build tools.

What's the difference between global and local installs?

Global installations provide CLI access to a package from any directory. Local installations are project-specific and are part of the project’s node_modules.