<!doctype html>
< html >
< title > folders< / title >
< meta http-equiv = "content-type" value = "text/html;utf-8" >
< link rel = "stylesheet" type = "text/css" href = "../style.css" >
< body >
< div id = "wrapper" >
< h1 > < a href = "../doc/folders.html" > folders< / a > < / h1 > < p > Folder Structures Used by npm< / p >
< h2 id = "DESCRIPTION" > DESCRIPTION< / h2 >
< p > npm puts various things on your computer. That's its job.< / p >
< p > This document will tell you what it puts where.< / p >
< h3 id = "tl-dr" > tl;dr< / h3 >
< ul > < li > Local install (default): puts stuff in < code > ./node_modules< / code > of the current
package root.< / li > < li > Global install (with < code > -g< / code > ): puts stuff in /usr/local or wherever node
is installed.< / li > < li > Install it < strong > locally< / strong > if you're going to < code > require()< / code > it.< / li > < li > Install it < strong > globally< / strong > if you're going to run it on the command line.< / li > < li > If you need both, then install it in both places, or use < code > npm link< / code > .< / li > < / ul >
< h3 id = "prefix-Configuration" > prefix Configuration< / h3 >
< p > The < code > prefix< / code > config defaults to the location where node is installed.
On most systems, this is < code > /usr/local< / code > , and most of the time is the same
as node's < code > process.installPrefix< / code > .< / p >
< p > On windows, this is the exact location of the node.exe binary. On Unix
systems, it's one level up, since node is typically installed at
< code > {prefix}/bin/node< / code > rather than < code > {prefix}/node.exe< / code > .< / p >
< p > When the < code > global< / code > flag is set, npm installs things into this prefix.
When it is not set, it uses the root of the current package, or the
current working directory if not in a package already.< / p >
< h3 id = "Node-Modules" > Node Modules< / h3 >
< p > Packages are dropped into the < code > node_modules< / code > folder under the < code > prefix< / code > .
When installing locally, this means that you can
< code > require("packagename")< / code > to load its main module, or
< code > require("packagename/lib/path/to/sub/module")< / code > to load other modules.< / p >
< p > Global installs on Unix systems go to < code > {prefix}/lib/node_modules< / code > .
Global installs on Windows go to < code > {prefix}/node_modules< / code > (that is, no
< code > lib< / code > folder.)< / p >
< p > If you wish to < code > require()< / code > a package, then install it locally.< / p >
< h3 id = "Executables" > Executables< / h3 >
< p > When in global mode, executables are linked into < code > {prefix}/bin< / code > on Unix,
or directly into < code > {prefix}< / code > on Windows.< / p >
< p > When in local mode, executables are linked into
< code > ./node_modules/.bin< / code > so that they can be made available to scripts run
through npm. (For example, so that a test runner will be in the path
when you run < code > npm test< / code > .)< / p >
< h3 id = "Man-Pages" > Man Pages< / h3 >
< p > When in global mode, man pages are linked into < code > {prefix}/share/man< / code > .< / p >
< p > When in local mode, man pages are not installed.< / p >
< p > Man pages are not installed on Windows systems.< / p >
< h3 id = "Cache" > Cache< / h3 >
< p > See < code > < a href = "../doc/cache.html" > cache(1)< / a > < / code > . Cache files are stored in < code > ~/.npm< / code > on Posix, or
< code > ~/npm-cache< / code > on Windows.< / p >
< p > This is controlled by the < code > cache< / code > configuration param.< / p >
< h3 id = "Temp-Files" > Temp Files< / h3 >
< p > Temporary files are stored by default in the folder specified by the
< code > tmp< / code > config, which defaults to the TMPDIR, TMP, or TEMP environment
variables, or < code > /tmp< / code > on Unix and < code > c:\windows\temp< / code > on Windows.< / p >
< p > Temp files are given a unique folder under this root for each run of the
program, and are deleted upon successful exit.< / p >
< h2 id = "More-Information" > More Information< / h2 >
< p > When installing locally, npm first tries to find an appropriate
< code > prefix< / code > folder. This is so that < code > npm install foo@1.2.3< / code > will install
to the sensible root of your package, even if you happen to have < code > cd< / code > ed
into some other folder.< / p >
< p > Starting at the $PWD, npm will walk up the folder tree checking for a
folder that contains either a < code > package.json< / code > file, or a < code > node_modules< / code >
folder. If such a thing is found, then that is treated as the effective
"current directory" for the purpose of running npm commands. (This
behavior is inspired by and similar to git's .git-folder seeking
logic when running git commands in a working dir.)< / p >
< p > If no package root is found, then the current folder is used.< / p >
< p > When you run < code > npm install foo@1.2.3< / code > , then the package is loaded into
the cache, and then unpacked into < code > ./node_modules/foo< / code > . Then, any of
foo's dependencies are similarly unpacked into
< code > ./node_modules/foo/node_modules/...< / code > .< / p >
< p > Any bin files are symlinked to < code > ./node_modules/.bin/< / code > , so that they may
be found by npm scripts when necessary.< / p >
< h3 id = "Global-Installation" > Global Installation< / h3 >
< p > If the < code > global< / code > configuration is set to true, then npm will
install packages "globally".< / p >
< p > For global installation, packages are installed roughly the same way,
but using the folders described above.< / p >
< h3 id = "Cycles-Conflicts-and-Folder-Parsimony" > Cycles, Conflicts, and Folder Parsimony< / h3 >
< p > Cycles are handled using the property of node's module system that it
walks up the directories looking for < code > node_modules< / code > folders. So, at every
stage, if a package is already installed in an ancestor < code > node_modules< / code >
folder, then it is not installed at the current location.< / p >
< p > Consider the case above, where < code > foo -> bar -> baz< / code > . Imagine if, in
addition to that, baz depended on bar, so you'd have:
< code > foo -> bar -> baz -> bar -> baz ...< / code > . However, since the folder
structure is: < code > foo/node_modules/bar/node_modules/baz< / code > , there's no need to
put another copy of bar into < code > .../baz/node_modules< / code > , since when it calls
require("bar"), it will get the copy that is installed in
< code > foo/node_modules/bar< / code > .< / p >
< p > This shortcut is only used if the exact same
version would be installed in multiple nested < code > node_modules< / code > folders. It
is still possible to have < code > a/node_modules/b/node_modules/a< / code > if the two
"a" packages are different versions. However, without repeating the
exact same package multiple times, an infinite regress will always be
prevented.< / p >
< p > Another optimization can be made by installing dependencies at the
highest level possible, below the localized "target" folder.< / p >
< h4 id = "Example" > Example< / h4 >
< p > Consider this dependency graph:< / p >
< pre > < code > foo
+-- blerg@1.2.5
+-- bar@1.2.3
| +-- blerg@1.x (latest=1.3.7)
| +-- baz@2.x
| | `-- quux@3.x
| | `-- bar@1.2.3 (cycle)
| `-- asdf@*
`-- baz@1.2.3
`-- quux@3.x
`-- bar< / code > < / pre >
< p > In this case, we might expect a folder structure like this:< / p >
< pre > < code > foo
+-- node_modules
+-- blerg (1.2.5) < ---[A]
+-- bar (1.2.3) < ---[B]
| +-- node_modules
| | `-- baz (2.0.2) < ---[C]
| | `-- node_modules
| | `-- quux (3.2.0)
| `-- asdf (2.3.4)
`-- baz (1.2.3) < ---[D]
`-- node_modules
`-- quux (3.2.0) < ---[E]< / code > < / pre >
< p > Since foo depends directly on bar@1.2.3 and baz@1.2.3, those are
installed in foo's < code > node_modules< / code > folder.< / p >
< p > Even though the latest copy of blerg is 1.3.7, foo has a specific
dependency on version 1.2.5. So, that gets installed at [A]. Since the
parent installation of blerg satisfie's bar's dependency on blerg@1.x,
it does not install another copy under [B].< / p >
< p > Bar [B] also has dependencies on baz and asdf, so those are installed in
bar's < code > node_modules< / code > folder. Because it depends on < code > baz@2.x< / code > , it cannot
re-use the < code > baz@1.2.3< / code > installed in the parent < code > node_modules< / code > folder [D],
and must install its own copy [C].< / p >
< p > Underneath bar, the < code > baz-> quux-> bar< / code > dependency creates a cycle.
However, because < code > bar< / code > is already in < code > quux< / code > 's ancestry [B], it does not
unpack another copy of bar into that folder.< / p >
< p > Underneath < code > foo-> baz< / code > [D], quux's [E] folder tree is empty, because its
dependency on bar is satisfied by the parent folder copy installed at [B].< / p >
< p > For a graphical breakdown of what is installed where, use < code > npm ls< / code > .< / p >
< h3 id = "Publishing" > Publishing< / h3 >
< p > Upon publishing, npm will look in the < code > node_modules< / code > folder. If any of
the items there are not in the < code > bundledDependencies< / code > array, then they will
not be included in the package tarball.< / p >
< p > This allows a package maintainer to install all of their dependencies
(and dev dependencies) locally, but only re-publish those items that
cannot be found elsewhere. See < code > < a href = "../doc/json.html" > json(1)< / a > < / code > for more information.< / p >
< h2 id = "SEE-ALSO" > SEE ALSO< / h2 >
< ul > < li > < a href = "../doc/faq.html" > faq(1)< / a > < / li > < li > < a href = "../doc/json.html" > json(1)< / a > < / li > < li > < a href = "../doc/install.html" > install(1)< / a > < / li > < li > < a href = "../doc/pack.html" > pack(1)< / a > < / li > < li > < a href = "../doc/cache.html" > cache(1)< / a > < / li > < li > < a href = "../doc/config.html" > config(1)< / a > < / li > < li > < a href = "../doc/publish.html" > publish(1)< / a > < / li > < / ul >
< / div >
< p id = "footer" > folders — npm@1.1.45< / p >
< script >
;(function () {
var wrapper = document.getElementById("wrapper")
var els = Array.prototype.slice.call(wrapper.getElementsByTagName("*"), 0)
.filter(function (el) {
return el.parentNode === wrapper
& & el.tagName.match(/H[1-6]/)
& & el.id
})
var l = 2
, toc = document.createElement("ul")
toc.innerHTML = els.map(function (el) {
var i = el.tagName.charAt(1)
, out = ""
while (i > l) {
out += "< ul > "
l ++
}
while (i < l ) {
out += "< / ul > "
l --
}
out += "< li > < a href = '#" + el.id + "' > " +
( el.innerText || el.text || el.innerHTML)
+ "< / a > "
return out
}).join("\n")
toc.id = "toc"
document.body.appendChild(toc)
})()
< / script >
< / body > < / html >
