Understanding Global and Local Packages in NPM

In this tutorial, we will dive into the differences between global and local packages in NPM (Node Package Manager). Understanding when to use global versus local packages is an essential part of managing your Node.js projects effectively. This tutorial was originally created in 2016, and we've included any critical updates to keep the information relevant for today's development environment.

What are Global and Local Packages?

Global Packages

Global packages are installed across your entire system and are accessible from any directory. These packages are typically used for command-line tools that you need to use globally, regardless of the current project directory.

• Installation Command: Use the -g flag with npm install to install a package globally:

  npm install -g package-name
  

• Example: Installing nodemon, a tool that automatically restarts your Node.js application when files change:

  npm install -g nodemon
  

Once installed globally, nodemon can be used from anywhere in your terminal.

Critical Update (2024): It is recommended to use npx for one-time usage of command-line tools instead of globally installing them. This reduces the risk of version conflicts and keeps your environment cleaner.

Local Packages

Local packages are installed within a specific project directory and are only accessible in that project. These packages are defined as dependencies in the project’s package.json file.

• Installation Command: To install a package locally, use npm install without the -g flag:

  npm install package-name
  

• Example: Installing express for use in a specific project:

  npm install express
  

This will create a node_modules folder in your project directory, containing the express package and any dependencies it requires.

When to Use Global vs. Local Packages

• Global Packages: Use when you need a tool available across your entire system, like linters or build tools (e.g., nodemon, gulp, or http-server).
• Local Packages: Use when the package is a library or dependency required only for a specific project. This ensures that different projects can use different versions of the same package without conflict.

Tip: As a best practice, limit the use of global packages and instead use npx or install locally whenever possible. This helps avoid issues with mismatched versions across projects.

How to List Installed Packages

Listing Global Packages

To list all the globally installed packages, use the following command:

npm list -g --depth=0

This command will show you all the global packages installed on your system without showing all their dependencies.

Listing Local Packages

To list the locally installed packages for a project, navigate to the project’s directory and run:

npm list --depth=0

This will list only the top-level packages installed in the current project directory.

Removing Packages

Uninstalling a Global Package

To remove a global package, use the -g flag with the npm uninstall command:

npm uninstall -g package-name

Uninstalling a Local Package

To remove a local package from your project, use the command without the -g flag:

npm uninstall package-name

This will also remove the package from the package.json file if it was listed as a dependency.

Conclusion

Understanding the differences between global and local packages in NPM is crucial for managing dependencies efficiently in your Node.js projects. Global packages are useful for command-line tools that need to be accessible from anywhere, while local packages keep project-specific dependencies isolated, ensuring compatibility across different projects.

Remember to be mindful of when to use global versus local installations. Where possible, use npx to execute commands without globally installing packages and always install project dependencies locally to maintain consistency and avoid conflicts.