Use npm to Manage Node.js Packages
Before using this guide, make sure that have both Node.js and npm installed on your server. If you do not have Node.js and npm installed, follow the install instructions for Node.js and npm in the Node.js install guide.
Basic NPM commands
- For a list of subcommands:
npm helpUsage: npm command
where command is one of:
add-user, adduser, apihelp, author, bin, bugs, c, cache,
completion, config, ddp, dedupe, deprecate, docs, edit,
explore, faq, find, find-dupes, get, help, help-search,
. . .
- For a brief summary of what each command does:
npm -lUsage: npm command
where command is one of:
adduser npm adduser
Then enter stuff at the prompts.
bin npm bin
npm bin -g
(just prints the bin folder)
. . .
- For a more detailed overview of each command:
npm help subcommand
- If you're unsure which command performs the action you want to perform, you may also search within the help topics:
npm help-search search_term
Now that npm is set up, and you know how to access the help file, we can start exploring. We'll start by learning how to ask for information about our system that relates to npm, but before we do, let's discuss the difference of Local Packages vs Global Packages.
Local vs global packages
When you create a Node.js application, you also create a directory structure that contains your application. In this structure there is a subdirectory called node_modules. This directory contains all the modules that can be locally installed.
- Make an empty directory structure that will serve as your package directory. For example:
mkdir -p ~/projects/test_package/node_modules
- Navigate to the directory you just created:
By default the majority of npm commands will assume you are referring to local packages. If you're not referring to a local package, you would use the -g or --global flags.
List installed packages
- List local packages in our test directory:
npm ls will show as empty since we haven't installed any Node.js packages yet. However, npm will install some packages globally by default.
- Use the -g flag to see those packages:
npm ls -g/home/demouser/.nvm/v0.11.13/lib
. . .
As seen above, there are quite a few global packages. There are other options you can use to modify the output. For example, you can use the -l or -a flags to show additional information.
Listing other information
- Aside from installed packages, we can query npm about other information:
npm rootnpm root should display the following output:
- List the top-level path for the package you're working on:
Note: You can also use the -g flag to see where the global files are being stored.
- Use npm bin to list where npm installs its executables:
npm binnpm bin should display the following output:/home/demouser/projects/test_package/node_modules/.bin
Exploring a package's files
- By using the explore subcommand, you can quickly go to the directory where your package is installed:
npm explore -g npm
When you're finished you can type 'exit' or ^D.
- Exit when you're finished:
Search for packages
To locate a Node.js package, you can simply search for it using npm. For example, if we needed the express package for our project (Express.js is a web framework), we can search for that package in the npm package archives. These archives are located on the npm website.
- Use npm to search for express.
npm search express
Note: Because this will generate a very long list, it's best to pipe it into less to make it easier to view.
- Another way to do it is by using a regular expression:
npm search /^express\[\ \]NAME DESCRIPTION AUTHOR DATE VERSION
express Sinatra inspiblue web development framework =tjholowaychuk… 2014-05-12 4.2.0
Note: If you receive too many results, it may be easier to go to the npm website. to find the name of the package. After you know the name of the package, you can install it.
- Because we need command line functionality, we will install express globally:
npm install -g express
This downloads and also installs the express package as well as all of its dependencies inside the global npm root directory.
- If you need the package in your local application's module directory so it can be included within the app with a require() line:
npm install express
Uninstall, de-duplicate, prune, and link packages
Because we want the package in our global and local scope, we will need to give it a way to have the package available in both locations.
- For example, we can uninstall our local version of the package:
npm uninstall express
- We can tell npm that we want to link our global copy of the local package:
npm link express
This creates a symbolic link in our node_modules directory that points to our global package which makes it available in both locations. You can also do the reverse of this by uninstalling the global version, then going into the local package and linking it globally.
- Uninstall the local link and global package:
npm uninstall express # This removes the symbolic link in local npm uninstall -g express # This removes the actual package in global
- Reinstall it as a local package:
npm install express
While the package is in our local application directory (~/projects/test_package/node_modules), it is not installed globally.
- To link it globally, we can go to the package directory and call the link subcommand without any arguments.
Now that it has the proper directory structure and files, we could use the same procedure to make our test package available to other packages we create. Some packages will have shared dependencies. For example, if our package directory has two modules that each need a package called A, that package will be installed twice - once under package1/nodemodules/A, and once under package2/nodemodules/A.
- We can use the dedupe subcommand to look for these cases and move the shared dependencies up a level. This allows both packages to find the single installation of the dependency.
- Dedupe the dependencies of our packages in the express directory:
This will locate two packages (mine and debug). The debug module is a dependency of another express module called "send". This would typically be deduplicated but since there is a version conflict, nothing is done.
For example, if you have moved your dependencies upwards by using dedupe, but you then uninstall the packages that previously owned the dependency package, the dependency is not removed due to the fact that it is not within the packages subdirectory anymore.
To work around this, you can tell npm to "prune" packages that aren't needed in your system. This refers to packages that aren't listed in you parent package's dependency list.
- Remove unwanted dependencies:
Finding and updating outdated packages
- Find outdated packages:
npm outdated. . .
Package Current Wanted Latest Location
type-is 1.1.0 1.1.0 1.2.0 express > type-is
debug 0.8.0 0.8.0 0.8.1 express > send > debug
This will list packages that have a more recent version available. It will display the installed applications, what your application requested and how that differs from your current version.
- To update your packages, you need to edit the version requested in the package's "package.json" followed by the update command: