What Is npm?
npm is a package manager commonly used with JavaScript and Node.js projects. It helps developers discover, install, update, remove, and manage software packages that their projects depend on.
npm also provides tools for running project scripts, managing dependencies, creating packages, and publishing packages to the npm registry.
What Does npm Stand For?
npm is historically associated with the phrase "Node Package Manager." Today, npm is commonly used as the name of the package manager, registry, and ecosystem surrounding JavaScript packages.
When developers say "install it with npm," they normally mean using the npm command-line interface to download and manage a package.
Why Do Developers Use npm?
Modern applications can contain thousands of pieces of reusable code. Instead of creating everything from zero, developers can use packages created and maintained by other developers.
For example, a project may need packages for:
- Web servers
- React applications
- Database access
- Authentication
- API requests
- Testing
- Build tools
- CSS processing
- Command-line applications
- Development utilities
npm and Node.js
npm is closely connected with the Node.js ecosystem. Installing Node.js using the official installer normally installs npm as well.
Check both installations from your terminal:
node -v
npm -v
If both commands display version numbers, the commands are available in your terminal. If a command is not recognized, check your installation and PATH configuration.
Download Node.js from the official Node.js website.
How to Create an npm Project
A common first step is creating a project directory and initializing it with npm.
mkdir my-project
cd my-project
npm init
npm asks several questions and then creates a
package.json file.
You can also use:
npm init -y
The -y option accepts the default answers and quickly creates
a basic package.json file.
What Is package.json?
The package.json file contains important information about a
JavaScript or Node.js project. It can describe the project, its dependencies,
its scripts, and its package metadata.
A simple example looks like this:
{
"name": "my-project",
"version": "1.0.0",
"description": "My first npm project",
"main": "index.js",
"scripts": {
"start": "node index.js"
}
}
This example defines a project name, version, description, entry-point
field, and start script. The main field is mainly relevant
when a package is imported by another project; it does not automatically
run the application.
Installing a Package
The main command for installing a package is:
npm install package-name
For example:
npm install express
npm installs Express and its required dependencies into the project's
node_modules directory. It also updates dependency information
in package.json and the lockfile when applicable.
Learn more in the official npm install documentation.
Installing a Specific Version
You can install a particular package version by adding the version number.
npm install express@5
This requests a version matching the major version 5 range. To request a specific version, use an exact version number:
npm install package-name@1.2.3
Check a package's documentation and compatibility before choosing a version.
Installing Development Dependencies
Some packages are needed only while developing, testing, or building an application. These can be installed as development dependencies.
npm install --save-dev eslint
Development dependencies are normally stored under
devDependencies in package.json.
Examples include linters, testing frameworks, and build tools.
What Is node_modules?
The node_modules folder contains packages installed for a project.
For example, after installing Express, a project may look like this:
my-project/
├── node_modules/
├── package.json
├── package-lock.json
└── index.js
The node_modules folder can become large because packages may depend on other packages.
Developers generally avoid committing node_modules to Git. Instead, they share package.json and the lockfile so dependencies can be installed again.
What Is package-lock.json?
npm can create a package-lock.json file that records the
resolved dependency tree and package versions. It helps reproduce
installations across different environments.
Avoid manually editing the lockfile unless you understand the changes. Normally, let npm update it when you install or update dependencies.
Installing All Project Dependencies
If a project already contains package.json, open a terminal in the project directory and run:
npm install
npm reads the dependency information and installs the required packages. If a suitable package-lock.json is present, npm uses it to help resolve the installation.
Removing a Package
To remove a package from your project, use:
npm uninstall package-name
For example:
npm uninstall express
This removes the package from the installed dependencies and updates the relevant project configuration.
Updating Packages
npm provides commands for checking and updating packages.
npm outdated
npm update
The first command lists outdated dependencies. The second updates packages according to the version ranges declared in the project.
An update does not necessarily install every newer major version. Read release notes before making major dependency changes.
Running npm Scripts
The scripts section of package.json allows developers to define useful commands.
{
"scripts": {
"start": "node index.js",
"test": "node test.js"
}
}
Run the scripts with:
npm start
npm test
For other named scripts, use npm run followed by the script name.
For example:
npm run build
The command will work only if a corresponding build script is defined.
Example Node.js Project
Suppose you want to create a small Node.js application.
mkdir hello-node
cd hello-node
npm init -y
Create a file named index.js with this code:
console.log("Hello from Node.js!");
Then run:
node index.js
The terminal should display:
Hello from Node.js!
You can later add npm packages when your project needs additional functionality.
Using an npm Package: Express Example
Express is a popular package for creating web servers with Node.js. First, create a project and install Express:
mkdir express-demo
cd express-demo
npm init -y
npm install express
For the following example, add
"type": "module" to the top level of package.json.
A minimal package.json can look like this:
{
"name": "express-demo",
"version": "1.0.0",
"type": "module",
"scripts": {
"start": "node index.js"
}
}
Create index.js:
import express from "express";
const app = express();
app.get("/", (req, res) => {
res.send("Hello World!");
});
app.listen(3000, () => {
console.log("Server running at http://localhost:3000");
});
Start the server:
npm start
Open http://localhost:3000 in a browser on the same machine
to test the example.
npm Registry
The npm registry is an online collection of JavaScript packages. Developers can search for packages, read their documentation, inspect versions, install packages, and publish their own packages.
The npm CLI uses the public npm registry by default, although it can also be configured to use other compatible registries.
Explore packages on the npm website.
Searching for Packages
You can search for packages from the terminal:
npm search express
To inspect packages installed in your project, run:
npm ls
To display only top-level packages, use:
npm ls --depth=0
Before installing an unfamiliar package, check its documentation, maintenance status, version history, and whether it meets your needs.
npm install vs npm ci
| Command | Common purpose |
|---|---|
npm install |
Install dependencies and update the lockfile when necessary. |
npm ci |
Perform a clean installation based on the existing lockfile. |
The npm ci command is useful in automated builds and continuous
integration. It requires a lockfile and fails if the lockfile and package.json
are not compatible. It also removes an existing node_modules folder before
installing.
Global npm Packages
npm can install certain command-line tools globally:
npm install -g package-name
A global installation can make a tool available outside a single project.
However, global installation is not necessary for every package.
For many tools, you can use npx or a project-local script.
Read the package's official instructions before installing command-line tools.
What Is npx?
npx is a command-line tool associated with npm that can run package commands without requiring you to permanently install every tool globally.
For example, you can start a Vite project with:
npm create vite@latest
Follow the prompts to select the project framework and options. The command may download packages, so you should review what you run.
npm Workspaces
npm supports workspaces, which help manage multiple related packages inside a single repository.
A workspace project might look like this:
company-project/
├── package.json
├── apps/
│ ├── website/
│ └── mobile/
└── packages/
└── shared/
Workspaces are useful when applications share code or need to be developed together. The root package.json must be configured for the workspaces.
npm Security
npm includes security-related commands such as:
npm audit
This command checks installed dependencies against known security advisories available to npm. It can identify reported vulnerabilities, but it does not guarantee that a project is completely secure.
You can also review available fixes with:
npm audit fix
Publishing an npm Package
Developers can publish reusable JavaScript packages to the npm registry. Before publishing, create an npm account and review the package contents to make sure you are not exposing secrets or private files.
A typical workflow includes:
- Prepare package.json and the package files.
- Test the package locally.
- Sign in to npm from the CLI.
- Choose the appropriate package name and version.
- Publish when you are ready.
Common commands include:
npm login
npm pack
npm publish
Publishing requires appropriate account permissions and a valid package configuration. Scoped packages may have additional visibility settings.
Read the official npm publishing guide before publishing.
Useful npm Commands
| Command | Purpose |
|---|---|
npm init |
Create a package.json file. |
npm install |
Install project dependencies. |
npm install package |
Install a package. |
npm uninstall package |
Remove a package. |
npm update |
Update dependencies within their declared ranges. |
npm outdated |
Check outdated packages. |
npm run |
List or run package scripts. |
npm start |
Run the start script, if defined. |
npm test |
Run the test script, if defined. |
npm search |
Search the package registry. |
npm ls |
List installed packages. |
npm audit |
Check for known dependency vulnerabilities. |
npm ci |
Clean-install dependencies from the lockfile. |
npm publish |
Publish a package. |
npm vs Yarn
npm and Yarn are package-management tools used in the JavaScript ecosystem. Both can install dependencies, manage project packages, and run scripts.
npm is convenient because it is normally installed with Node.js. Yarn is an alternative with its own commands and configuration. Choose the tool that fits your project and follow one consistent package-management workflow.
npm vs pnpm
pnpm is another JavaScript package manager. It uses a different approach to storing and linking dependencies, which can reduce repeated storage across projects.
npm and pnpm can both manage project dependencies. Their lockfiles and configuration are different, so avoid switching tools in a project without understanding the effects.
npm vs Bun
npm is primarily a package manager and command-line tool in the Node.js ecosystem. Bun is a JavaScript runtime and toolkit that also includes a package manager, test runner, and bundler.
Both support JavaScript development, but they provide different tools and workflows.
npm vs Deno
Deno is a JavaScript and TypeScript runtime with integrated development tools. Modern Deno projects can also use npm packages.
npm remains widely used for managing dependencies in Node.js projects. The best choice depends on the application and the runtime you plan to use.
Common npm Errors and Troubleshooting
1. Command not found
If the terminal cannot find node or npm, verify that Node.js is installed and that its installation directory is available through your PATH. Restart the terminal after installation if necessary.
2. EACCES or permission errors
These errors can occur when npm cannot write to a directory. Check directory permissions and use the recommended setup for your operating system. Avoid using administrator privileges for every npm command.
3. Package not found
Check the package name, registry configuration, and internet connection. A package may be private, unpublished, or unavailable from your configured registry.
4. Dependency conflicts
Review the error output to identify incompatible package versions. Check the packages' supported versions before changing dependencies.
5. Installation fails
Read the complete error message first. Verify your Node.js version, internet connection, disk space, and package configuration. Do not delete the lockfile as the first troubleshooting step.
6. Application does not start
Check that you are in the correct project folder, that the entry-point file exists, and that the required script is defined in package.json.
Recommended Beginner Workflow
- Install Node.js from the official website.
- Check Node.js and npm versions.
- Create a project folder.
- Run
npm init -y. - Install only the packages you need.
- Write your application code.
- Add useful scripts to package.json.
- Run and test the application.
- Keep package.json and package-lock.json together.
- Review dependency updates and security warnings carefully.
Simple npm Project Structure
my-app/
├── node_modules/
├── package.json
├── package-lock.json
├── index.js
├── README.md
└── .gitignore
A real project can contain many additional files and folders depending on
the framework and application. The .gitignore file commonly
includes node_modules/ so installed dependencies are not
committed to Git.
Practical Exercises for Beginners
Try these exercises to practice what you have learned:
- Check your installed Node.js and npm versions.
- Create a folder called
practice-npm. - Initialize the project using
npm init -y. - Install a small package and inspect package.json.
- Run
npm ls --depth=0to list top-level packages. - Create a start script and run it using
npm start. - Uninstall the package and inspect the changes.
Frequently Asked Questions
Is npm a programming language?
No. npm is a package manager and command-line tool used mainly in the JavaScript and Node.js ecosystem.
Do I need Node.js to use npm?
The standard npm CLI runs with Node.js. Installing Node.js using its official installer normally includes npm.
What is npm install?
It installs packages and their dependencies. When run in a project that has package.json, it normally installs the project's declared dependencies.
What is package.json?
It is a project configuration file that can describe the project, dependencies, scripts, and other package information.
What is node_modules?
It is the directory where npm normally places locally installed packages and their dependencies.
What is package-lock.json?
It records the resolved dependency tree to help reproduce installations consistently across environments.
Can I create my own npm package?
Yes. Developers can create reusable JavaScript packages and publish them to the npm registry when they meet the publishing requirements.
Is npm free?
npm provides access to a public registry of packages and free package-management features. Some npm products and services also have paid plans.
Conclusion
npm is an important part of modern JavaScript development. It helps developers install and manage packages, control dependencies, run project scripts, create reusable packages, and work with the wider JavaScript ecosystem.
If you are learning Node.js, React, Express, Vite, or other JavaScript technologies, understanding npm will make your development workflow easier.