mirror of https://github.com/nodejs/node.git
164 lines
9.8 KiB
HTML
164 lines
9.8 KiB
HTML
<h1><a href="cli/npm.html">npm</a></h1> <p>a JavaScript package manager</p>
|
|
<p><a href="https://travis-ci.org/npm/npm"><img src="https://img.shields.io/travis/npm/npm/master.svg" alt="Build Status"></a></p>
|
|
<h2 id="synopsis">SYNOPSIS</h2>
|
|
<p>This is just enough info to get you up and running.</p>
|
|
<p>Much more info available via <code>npm help</code> once it's installed.</p>
|
|
<h2 id="important">IMPORTANT</h2>
|
|
<p><strong>You need node v0.8 or higher to run this program.</strong></p>
|
|
<p>To install an old <strong>and unsupported</strong> version of npm that works on node 0.3
|
|
and prior, clone the git repo and dig through the old tags and branches.</p>
|
|
<h2 id="super-easy-install">Super Easy Install</h2>
|
|
<p>npm comes with <a href="http://nodejs.org/download/">node</a> now.</p>
|
|
<h3 id="windows-computers">Windows Computers</h3>
|
|
<p><a href="http://nodejs.org/download/">Get the MSI</a>. npm is in it.</p>
|
|
<h3 id="apple-macintosh-computers">Apple Macintosh Computers</h3>
|
|
<p><a href="http://nodejs.org/download/">Get the pkg</a>. npm is in it.</p>
|
|
<h3 id="other-sorts-of-unices">Other Sorts of Unices</h3>
|
|
<p>Run <code>make install</code>. npm will be installed with node.</p>
|
|
<p>If you want a more fancy pants install (a different version, customized
|
|
paths, etc.) then read on.</p>
|
|
<h2 id="fancy-install-unix-">Fancy Install (Unix)</h2>
|
|
<p>There's a pretty robust install script at
|
|
<a href="https://www.npmjs.com/install.sh">https://www.npmjs.com/install.sh</a>. You can download that and run it.</p>
|
|
<p>Here's an example using curl:</p>
|
|
<pre><code class="lang-sh">curl -L https://www.npmjs.com/install.sh | sh
|
|
</code></pre>
|
|
<h3 id="slightly-fancier">Slightly Fancier</h3>
|
|
<p>You can set any npm configuration params with that script:</p>
|
|
<pre><code class="lang-sh">npm_config_prefix=/some/path sh install.sh
|
|
</code></pre>
|
|
<p>Or, you can run it in uber-debuggery mode:</p>
|
|
<pre><code class="lang-sh">npm_debug=1 sh install.sh
|
|
</code></pre>
|
|
<h3 id="even-fancier">Even Fancier</h3>
|
|
<p>Get the code with git. Use <code>make</code> to build the docs and do other stuff.
|
|
If you plan on hacking on npm, <code>make link</code> is your friend.</p>
|
|
<p>If you've got the npm source code, you can also semi-permanently set
|
|
arbitrary config keys using the <code>./configure --key=val ...</code>, and then
|
|
run npm commands by doing <code>node cli.js <cmd> <args></code>. (This is helpful
|
|
for testing, or running stuff without actually installing npm itself.)</p>
|
|
<h2 id="windows-install-or-upgrade">Windows Install or Upgrade</h2>
|
|
<p>You can download a zip file from <a href="https://github.com/npm/npm/releases">https://github.com/npm/npm/releases</a>, and
|
|
unpack it in the <code>node_modules\npm\</code> folder inside node's installation folder.</p>
|
|
<p>To upgrade to npm 2, follow the Windows upgrade instructions in
|
|
the npm Troubleshooting Guide:</p>
|
|
<p><a href="https://github.com/npm/npm/wiki/Troubleshooting#upgrading-on-windows">https://github.com/npm/npm/wiki/Troubleshooting#upgrading-on-windows</a></p>
|
|
<p>If that's not fancy enough for you, then you can fetch the code with
|
|
git, and mess with it directly.</p>
|
|
<h2 id="installing-on-cygwin">Installing on Cygwin</h2>
|
|
<p>No.</p>
|
|
<h2 id="uninstalling">Uninstalling</h2>
|
|
<p>So sad to see you go.</p>
|
|
<pre><code class="lang-sh">sudo npm uninstall npm -g
|
|
</code></pre>
|
|
<p>Or, if that fails,</p>
|
|
<pre><code class="lang-sh">sudo make uninstall
|
|
</code></pre>
|
|
<h2 id="more-severe-uninstalling">More Severe Uninstalling</h2>
|
|
<p>Usually, the above instructions are sufficient. That will remove
|
|
npm, but leave behind anything you've installed.</p>
|
|
<p>If you would like to remove all the packages that you have installed,
|
|
then you can use the <code>npm ls</code> command to find them, and then <code>npm rm</code> to
|
|
remove them.</p>
|
|
<p>To remove cruft left behind by npm 0.x, you can use the included
|
|
<code>clean-old.sh</code> script file. You can run it conveniently like this:</p>
|
|
<pre><code class="lang-sh">npm explore npm -g -- sh scripts/clean-old.sh
|
|
</code></pre>
|
|
<p>npm uses two configuration files, one for per-user configs, and another
|
|
for global (every-user) configs. You can view them by doing:</p>
|
|
<pre><code class="lang-sh">npm config get userconfig # defaults to ~/.npmrc
|
|
npm config get globalconfig # defaults to /usr/local/etc/npmrc
|
|
</code></pre>
|
|
<p>Uninstalling npm does not remove configuration files by default. You
|
|
must remove them yourself manually if you want them gone. Note that
|
|
this means that future npm installs will not remember the settings that
|
|
you have chosen.</p>
|
|
<h2 id="using-npm-programmatically">Using npm Programmatically</h2>
|
|
<p>Although npm can be used programmatically, its API is meant for use by the CLI
|
|
<em>only</em>, and no guarantees are made regarding its fitness for any other purpose.
|
|
If you want to use npm to reliably perform some task, the safest thing to do is
|
|
to invoke the desired <code>npm</code> command with appropriate arguments.</p>
|
|
<p>The semantic version of npm refers to the CLI itself, rather than the
|
|
underlying API. <em>The internal API is not guaranteed to remain stable even when
|
|
npm's version indicates no breaking changes have been made according to
|
|
semver.</em></p>
|
|
<p>If you <em>still</em> would like to use npm programmatically, it's <em>possible</em>. The API
|
|
isn't very well documented, but it <em>is</em> rather simple.</p>
|
|
<p>Eventually, npm will be just a thin CLI wrapper around the modules that it
|
|
depends on, but for now, there are some things that only the CLI can do. You
|
|
should try using one of npm's dependencies first, and only use the API if what
|
|
you're trying to do is only supported by npm itself.</p>
|
|
<pre><code class="lang-javascript">var npm = require("npm")
|
|
npm.load(myConfigObject, function (er) {
|
|
if (er) return handlError(er)
|
|
npm.commands.install(["some", "args"], function (er, data) {
|
|
if (er) return commandFailed(er)
|
|
// command succeeded, and data might have some info
|
|
})
|
|
npm.registry.log.on("log", function (message) { .... })
|
|
})
|
|
</code></pre>
|
|
<p>The <code>load</code> function takes an object hash of the command-line configs.
|
|
The various <code>npm.commands.<cmd></code> functions take an <strong>array</strong> of
|
|
positional argument <strong>strings</strong>. The last argument to any
|
|
<code>npm.commands.<cmd></code> function is a callback. Some commands take other
|
|
optional arguments. Read the source.</p>
|
|
<p>You cannot set configs individually for any single npm function at this
|
|
time. Since <code>npm</code> is a singleton, any call to <code>npm.config.set</code> will
|
|
change the value for <em>all</em> npm commands in that process.</p>
|
|
<p>See <code>./bin/npm-cli.js</code> for an example of pulling config values off of the
|
|
command line arguments using nopt. You may also want to check out <code>npm
|
|
help config</code> to learn about all the options you can set there.</p>
|
|
<h2 id="more-docs">More Docs</h2>
|
|
<p>Check out the <a href="https://docs.npmjs.com/">docs</a>,
|
|
especially the <a href="https://docs.npmjs.com/misc/faq">faq</a>.</p>
|
|
<p>You can use the <code>npm help</code> command to read any of them.</p>
|
|
<p>If you're a developer, and you want to use npm to publish your program,
|
|
you should <a href="https://docs.npmjs.com/misc/developers">read this</a></p>
|
|
<h2 id="legal-stuff">Legal Stuff</h2>
|
|
<p>"npm" and "The npm Registry" are owned by npm, Inc.
|
|
All rights reserved. See the included LICENSE file for more details.</p>
|
|
<p>"Node.js" and "node" are trademarks owned by Joyent, Inc.</p>
|
|
<p>Modules published on the npm registry are not officially endorsed by
|
|
npm, Inc. or the Node.js project.</p>
|
|
<p>Data published to the npm registry is not part of npm itself, and is
|
|
the sole property of the publisher. While every effort is made to
|
|
ensure accountability, there is absolutely no guarantee, warranty, or
|
|
assertion expressed or implied as to the quality, fitness for a
|
|
specific purpose, or lack of malice in any given npm package.</p>
|
|
<p>If you have a complaint about a package in the public npm registry,
|
|
and cannot <a href="https://docs.npmjs.com/misc/disputes">resolve it with the package
|
|
owner</a>, please email
|
|
<a href="mailto:support@npmjs.com">support@npmjs.com</a> and explain the situation.</p>
|
|
<p>Any data published to The npm Registry (including user account
|
|
information) may be removed or modified at the sole discretion of the
|
|
npm server administrators.</p>
|
|
<h3 id="in-plainer-english">In plainer english</h3>
|
|
<p>npm is the property of npm, Inc.</p>
|
|
<p>If you publish something, it's yours, and you are solely accountable
|
|
for it.</p>
|
|
<p>If other people publish something, it's theirs.</p>
|
|
<p>Users can publish Bad Stuff. It will be removed promptly if reported.
|
|
But there is no vetting process for published modules, and you use
|
|
them at your own risk. Please inspect the source.</p>
|
|
<p>If you publish Bad Stuff, we may delete it from the registry, or even
|
|
ban your account in extreme cases. So don't do that.</p>
|
|
<h2 id="bugs">BUGS</h2>
|
|
<p>When you find issues, please report them:</p>
|
|
<ul>
|
|
<li>web:
|
|
<a href="https://github.com/npm/npm/issues">https://github.com/npm/npm/issues</a></li>
|
|
</ul>
|
|
<p>Be sure to include <em>all</em> of the output from the npm command that didn't work
|
|
as expected. The <code>npm-debug.log</code> file is also helpful to provide.</p>
|
|
<p>You can also look for isaacs in #node.js on irc://irc.freenode.net. He
|
|
will no doubt tell you to put the output in a gist or email.</p>
|
|
<h2 id="see-also">SEE ALSO</h2>
|
|
<ul>
|
|
<li><a href="cli/npm.html">npm(1)</a></li>
|
|
<li><a href="misc/npm-faq.html">npm-faq(7)</a></li>
|
|
<li><a href="cli/npm-help.html">npm-help(1)</a></li>
|
|
<li><a href="misc/npm-index.html">npm-index(7)</a></li>
|
|
</ul>
|
|
|