How To Use npm to Manage Node.js Packages on a Linux Server
In this guide, we will talk about how to use
npm, a Node.js package management system, to manage Node.js packages on your server. Using this utility, you can easily satisfy application dependencies, search for packages, and manage installations.
We'll assume that you have both Node.js and
npm installed. You can follow the guide above to get these running on Ubuntu 14.04. I recommend using the
nvm method covered in that tutorial.
If you just want to get started quickly, you can also find the packages in Ubuntu 14.04's repositories and install them by typing:
sudo apt-get update sudo apt-get install nodejs npm
Getting Familiar with npm
Now that you have the necessary components installed, we can get started.
The first thing we are going to do is add some
npm auto-complete functionality to our shell by adding some information to the bottom of our shell configuration file.
You can do that by typing:
npm completion >> ~/.bashrc
Now, just source the configuration file to re-read the new changes you just added:
Now, npm should be able to automatically complete its commands by hitting the
To get ourselves oriented, the best thing to do is get familiar with the help functionality that npm provides. To get an idea of the subcommands that are available within npm, you can type:
Usage: 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, . . .
To get a brief summary of what these subcommands mean, you can type:
Usage: 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) . . .
You can get a much more extensive overview of each of these commands by using the following format:
npm help subcommand
This will bring up a separate man page for the desired subcommand.
If you don't know which command covers the action you wish to perform, you can also search within the help topics by using something like:
npm help-search search_term
Finding Information about your System
Now that you have set up and know how to access its built-in help, we can explore. Let's start by learning how to ask for information about our system that relates to npm.
Before we do that, we should talk about the difference between local and global packages.
Local vs Global Packages
When creating a Node.js application, you create a directory structure to hold your application. Within the project's directory, there will be a subdirectory called
node_modules. This holds all of the modules that you can install locally for your project.
Let's create an empty directory structure that will serve as our package directory as an example:
mkdir -p ~/projects/test_package/node_modules cd ~/projects/test_package
require() method. This is what you need most of the time for a package.
If you need to use a package's command line capabilities, you should install it globally. Globally installed applications are kept in the
Knowing this, you can see how we will have functionality that is associated with each specific type of package. By default, most npm commands will assume that you are talking about local packages, unless you pass the
Listing Packages Installed on our System
Now that you know the difference between local and global packages, we can move on. So, to list the (locally installed) Node.js packages available in our
test_package directory, we can type:
/home/demouser/projects/test_package └── (empty)
Since we haven't installed any Node.js packages for our application yet, this shows up empty.
However, npm installs some packages globally automatically. Let's pass the
-g flag to see:
npm ls -g
/home/demouser/.nvm/v0.11.13/lib └─┬ firstname.lastname@example.org ├── email@example.com ├── firstname.lastname@example.org ├── email@example.com ├── firstname.lastname@example.org ├── email@example.com . . .
As you can see, there are quite a few global packages. They are shown in a dependency tree format.
There are some other options you can use to modify the output. You can use the
-a flags to get additional information. You can view this information in JSON by optionally passing the
Querying for Other Information
Apart from simply asking npm about installed packages, we can ask it some other information about its environment.
We can see what npm refers to as the root module directory within the local package hierarchy by typing:
You can get the top-level path for the package you're working on by using the
These can also be used with the
-g flag to see where the global files are stored.
To see where npm will install executables, you can find the
bin directory for the current project:
Exploring a Package's Files
To quickly go to the directory location where a package is installed, you can actually just use the
explore subcommand. This will open a subshell in the directory where the package is installed.
For instance, we can open a subshell in the directory where npm itself is installed by typing:
npm explore -g npm
Exploring /home/demouser/.nvm/v0.11.13/lib/node_modules/npm Type 'exit' or ^D when finished
You can manipulate or explore the files in this directory and then exit out of the subshell to return to what you were previously doing.
Using npm as a Package Manager
We've covered a lot of ground so far, but we've skirted the main functionality of npm until now. The main reason that people use npm is for its package management capabilities.
Searching for and Installing Packages
When you need a Node.js package, you can search for it using npm. Let's pretend we're going to need the
express package for our project. Express is a web framework.
We can search for this package in the npm package archives, which are located at the npm website:
npm search express
This will actually return an extremely long list, since express is a very popular package. You can pipe this into a pager like
less to view it easier. We can also use regular expressions (with some funky characters to escape shell interpretation) like this:
npm search /^express\[\ \]
NAME DESCRIPTION AUTHOR DATE VERSIO express Sinatra inspired web development framework =tjholowaychuk… 2014-05-12 4.2.0
If you are getting too many results though, it might be easier just to go to the npm site to see what the exact package is called.
When you know the name of the package, you can install it. Since we need the command line functionality of express, we'll install it globally:
npm install -g express
This will download and install the express package and all of its dependencies into the global npm root directory.
If we want the package in our local application's module directory so that it can be included in the app with a
require() line, you can type:
cd ~/projects/test_package npm install express
We don't actually need to install the package and dependencies in both places however, and we'll show you how to avoid this below.
Uninstalling, De-duplicating, Pruning, and Linking Packages
Since we want this package in both our global and local scope, we need to provide it with a way to have this package available in both places.
First, let's uninstall our local version of the package, like this:
npm uninstall express
Now, we can tell npm that we want to link our global copy to the local package, like this:
npm link express
This will create a symbolic link within our
node_modules directory to our global package, making it available in both places.
We could have done the reverse of this by uninstalling the global version, going into the local package and linking globally. We could do that like this.
First, uninstall the local link and the global package:
npm uninstall express # This removes the symbolic link in local npm uninstall -g express # This removes the actual package in global
Reinstall the package as a local package:
npm install express
The package is in our local application directory (
~/projects/test_package/node_modules), but not installed globally. We can link it globally to going to the package directory and calling the link subcommand with no additional arguments:
cd ~/projects/test_package/node_modules/express npm link
We could use this same procedure to make our own
test_package available to other packages we are creating (assuming it had the proper directory structure and files, which it does not now).
While we are installing and shuffling our packages around, we should take advantage of the
Our packages have dependencies installed under them in the hierarchy. However, some packages may have shared dependencies. If our package directory contains two modules that each require a package called "blah", it will be installed twice, once under "package1/nodemodules/blah" and one under "package2/nodemodules/blah".
dedupe subcommand looks for these cases and moves shared dependencies up a level, where both packages will find the single installation of the dependency.
For example, we can try to dedupe the dependencies of our packages in the express directory. We can do this in the package directory like this:
cd ~/projects/test_package/node_modules/express npm dedupe
This will find two packages (mime and debug). The debug module is actually also a dependency of another express module dependency called "send". This would normally be deduplicated, but there is a version conflict, so nothing is done in this instance.
Let's say that you have deduped your packages, which moves some dependencies upwards, but then you uninstall the packages that formerly owned the dependency package. The dependency will not be removed because it is not within the packages subdirectory anymore.
In these cases, we can tell npm to "prune" packages that aren't needed in our system. This means packages that aren't listed in our parent package's dependency list.
You can remove the unwanted dependencies by calling:
This will remove the unneeded packages.
Finding Outdated Packages and Updating them
If you need to find out which packages are out of date, you can do so by typing something like this:
. . . 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 give you a list of packages that have more recent versions available. It will give you a chart showing what is installed, what your application requested, and how that differs from the current version.
If you want to update your packages, you should edit the version requested in the package's
package.json and then issue the update command:
We've covered some of the more common ways to use npm as a package manager. You should now have a good idea of how to acquire and manage other people's packages for use in your own development.
In our next guide on npm, we'll go over how to configure npm to alter its behavior, how to create packages with npm, and how to publish your packages and interact with the npm website.