Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 261 lines (168 sloc) 8.103 kb
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
1 npm(1) -- node package manager
2 ==============================
4626dfa Initial drop. Ugly, sketchy, and not even yet quite a "work in progress...
isaacs authored
3
32f2673 @isaacs Add README as proper html/manpage doc
isaacs authored
4 ## SYNOPSIS
5
069a27c @isaacs Add a simpler install process up near the top.
isaacs authored
6 This is just enough info to get you up and running.
b3f1673 @isaacs another note pointing users to the documentation
isaacs authored
7
5e04f23 @isaacs Spruce up the install cmd a bit
isaacs authored
8 Much more info available via `npm help` once it's installed.
841f3b5 @isaacs Move the installing section up to the top
isaacs authored
9
266f1c9 @isaacs Update the README with more helpful info.
isaacs authored
10 ## IMPORTANT
11
b16093e @isaacs Make readme a bit more accurate
isaacs authored
12 **You need node v0.6 or higher to run this program.**
266f1c9 @isaacs Update the README with more helpful info.
isaacs authored
13
492dff3 @isaacs README updates. Legalese, proper instructions, etc.
isaacs authored
14 To install an old **and unsupported** version of npm that works on node 0.3
199cb34 @isaacs Don't suggest how to use old versions
isaacs authored
15 and prior, clone the git repo and dig through the old tags and branches.
266f1c9 @isaacs Update the README with more helpful info.
isaacs authored
16
b16093e @isaacs Make readme a bit more accurate
isaacs authored
17 ## Super Easy Install
841f3b5 @isaacs Move the installing section up to the top
isaacs authored
18
b16093e @isaacs Make readme a bit more accurate
isaacs authored
19 npm comes with node now.
d49a887 @isaacs add some more installation suggestions/options
isaacs authored
20
b16093e @isaacs Make readme a bit more accurate
isaacs authored
21 ### Windows Computers
36b4215 @isaacs Add clean=yes/no instructions to README
isaacs authored
22
b16093e @isaacs Make readme a bit more accurate
isaacs authored
23 Get the MSI. npm is in it.
36b4215 @isaacs Add clean=yes/no instructions to README
isaacs authored
24
b16093e @isaacs Make readme a bit more accurate
isaacs authored
25 ### Apple Macintosh Computers
36b4215 @isaacs Add clean=yes/no instructions to README
isaacs authored
26
b16093e @isaacs Make readme a bit more accurate
isaacs authored
27 Get the pkg. npm is in it.
1c71826 @isaacs Update windows install instructions
isaacs authored
28
b16093e @isaacs Make readme a bit more accurate
isaacs authored
29 ### Other Sorts of Unices
1c71826 @isaacs Update windows install instructions
isaacs authored
30
b16093e @isaacs Make readme a bit more accurate
isaacs authored
31 Run `make install`. npm will be installed with node.
1c71826 @isaacs Update windows install instructions
isaacs authored
32
b16093e @isaacs Make readme a bit more accurate
isaacs authored
33 If you want a more fancy pants install (a different version, customized
34 paths, etc.) then read on.
1c71826 @isaacs Update windows install instructions
isaacs authored
35
b16093e @isaacs Make readme a bit more accurate
isaacs authored
36 ## Fancy Install (Unix)
ac51a71 @isaacs Update node version requirement for Windows
isaacs authored
37
b16093e @isaacs Make readme a bit more accurate
isaacs authored
38 To install npm with one command, do this:
1c71826 @isaacs Update windows install instructions
isaacs authored
39
b16093e @isaacs Make readme a bit more accurate
isaacs authored
40 curl http://npmjs.org/install.sh | sh
1c71826 @isaacs Update windows install instructions
isaacs authored
41
b16093e @isaacs Make readme a bit more accurate
isaacs authored
42 To skip the npm 0.x cleanup, do this:
1c71826 @isaacs Update windows install instructions
isaacs authored
43
b16093e @isaacs Make readme a bit more accurate
isaacs authored
44 curl http://npmjs.org/install.sh | clean=no sh
1c71826 @isaacs Update windows install instructions
isaacs authored
45
b16093e @isaacs Make readme a bit more accurate
isaacs authored
46 To say "yes" to the 0.x cleanup, but skip the prompt:
543790f @isaacs Update install instructions
isaacs authored
47
b16093e @isaacs Make readme a bit more accurate
isaacs authored
48 curl http://npmjs.org/install.sh | clean=yes sh
543790f @isaacs Update install instructions
isaacs authored
49
b16093e @isaacs Make readme a bit more accurate
isaacs authored
50 If you get permission errors, you'll need to **run** the script as root.
51 (Note, just putting `sudo` in front of the `curl` will **fetch** the script
52 as root.)
1c71826 @isaacs Update windows install instructions
isaacs authored
53
b16093e @isaacs Make readme a bit more accurate
isaacs authored
54 ### Slightly Fancier
1c71826 @isaacs Update windows install instructions
isaacs authored
55
b16093e @isaacs Make readme a bit more accurate
isaacs authored
56 You can set any npm configuration params with that script:
1c71826 @isaacs Update windows install instructions
isaacs authored
57
b16093e @isaacs Make readme a bit more accurate
isaacs authored
58 curl http://npmjs.org/install.sh | npm_config_prefix=/some/path sh
1c71826 @isaacs Update windows install instructions
isaacs authored
59
b16093e @isaacs Make readme a bit more accurate
isaacs authored
60 Or, you can run it in uber-debuggery mode:
1c71826 @isaacs Update windows install instructions
isaacs authored
61
b16093e @isaacs Make readme a bit more accurate
isaacs authored
62 curl http://npmjs.org/install.sh | npm_debug=1 sh
1c71826 @isaacs Update windows install instructions
isaacs authored
63
b16093e @isaacs Make readme a bit more accurate
isaacs authored
64 ### Even Fancier
1c71826 @isaacs Update windows install instructions
isaacs authored
65
b16093e @isaacs Make readme a bit more accurate
isaacs authored
66 Get the code with git. Use `make` to build the docs and do other stuff.
67 If you plan on hacking on npm, `make link` is your friend.
6740f2a @isaacs Add 'curl|sudo sh' instructions
isaacs authored
68
b16093e @isaacs Make readme a bit more accurate
isaacs authored
69 If you've got the npm source code, you can also semi-permanently set
70 arbitrary config keys using the `./configure --key=val ...`, and then
71 run npm commands by doing `node cli.js <cmd> <args>`. (This is helpful
72 for testing, or running stuff without actually installing npm itself.)
6740f2a @isaacs Add 'curl|sudo sh' instructions
isaacs authored
73
b16093e @isaacs Make readme a bit more accurate
isaacs authored
74 ## Fancy Windows Install
6740f2a @isaacs Add 'curl|sudo sh' instructions
isaacs authored
75
b16093e @isaacs Make readme a bit more accurate
isaacs authored
76 You can download a zip file from <http://npmjs.org/dist/>, and unpack it
77 in the same folder where node.exe lives.
543790f @isaacs Update install instructions
isaacs authored
78
b16093e @isaacs Make readme a bit more accurate
isaacs authored
79 If that's not fancy enough for you, then you can fetch the code with
80 git, and mess with it directly.
543790f @isaacs Update install instructions
isaacs authored
81
1c71826 @isaacs Update windows install instructions
isaacs authored
82 ## Installing on Cygwin
83
b3dcb9b @isaacs Update the README with better permission windows stuff
isaacs authored
84 No.
1c71826 @isaacs Update windows install instructions
isaacs authored
85
6740f2a @isaacs Add 'curl|sudo sh' instructions
isaacs authored
86 ## Dev Install
87
88 To install the latest **unstable** development version from git:
5d6fb4b @isaacs the install script sometimes fails.
isaacs authored
89
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
90 git clone https://github.com/isaacs/npm.git
91 cd npm
543790f @isaacs Update install instructions
isaacs authored
92 sudo make install # (or: `node cli.js install -gf`)
5d6fb4b @isaacs the install script sometimes fails.
isaacs authored
93
5e04f23 @isaacs Spruce up the install cmd a bit
isaacs authored
94 If you're sitting in the code folder reading this document in your
95 terminal, then you've already got the code. Just do:
96
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
97 sudo make install
5e04f23 @isaacs Spruce up the install cmd a bit
isaacs authored
98
99 and npm will install itself.
100
b3dcb9b @isaacs Update the README with better permission windows stuff
isaacs authored
101 ## Permissions when Using npm to Install Other Stuff
0164a0d @isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
102
8ee3c3e @isaacs Closes GH-623 correct branch checkout instruction
isaacs authored
103 **tl;dr**
104
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
105 * Use `sudo` for greater safety. Or don't, if you prefer not to.
8ee3c3e @isaacs Closes GH-623 correct branch checkout instruction
isaacs authored
106 * npm will downgrade permissions if it's root before running any build
107 scripts that package authors specified.
0164a0d @isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
108
678d2e8 @isaacs change readme to suggest root usage
isaacs authored
109 ### More details...
0164a0d @isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
110
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
111 As of version 0.3, it is recommended to run npm as root.
678d2e8 @isaacs change readme to suggest root usage
isaacs authored
112 This allows npm to change the user identifier to the `nobody` user prior
113 to running any package build or test commands.
3901ac1 @isaacs Be more specific with the chown instructions
isaacs authored
114
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
115 If you are not the root user, or if you are on a platform that does not
116 support uid switching, then npm will not attempt to change the userid.
0164a0d @isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
117
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
118 If you would like to ensure that npm **always** runs scripts as the
119 "nobody" user, and have it fail if it cannot downgrade permissions, then
120 set the following configuration param:
d49a887 @isaacs add some more installation suggestions/options
isaacs authored
121
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
122 npm config set unsafe-perm false
069a27c @isaacs Add a simpler install process up near the top.
isaacs authored
123
78a05bb Added syntax highlighting for codeblocks (README.md).
Zearin authored
124 This will prevent running in unsafe mode, even as non-root users.
069a27c @isaacs Add a simpler install process up near the top.
isaacs authored
125
c71ae65 @isaacs version notes for 0.1.11
isaacs authored
126 ## Uninstalling
127
128 So sad to see you go.
129
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
130 sudo npm uninstall npm -g
c71ae65 @isaacs version notes for 0.1.11
isaacs authored
131
132 Or, if that fails,
133
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
134 sudo make uninstall
d9e9c14 @isaacs Point developers to the docs
isaacs authored
135
c7dee39 @isaacs Add npm removal instructions
isaacs authored
136 ## More Severe Uninstalling
137
138 Usually, the above instructions are sufficient. That will remove
139 npm, but leave behind anything you've installed.
140
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
141 If you would like to remove all the packages that you have installed,
142 then you can use the `npm ls` command to find them, and then `npm rm` to
143 remove them.
c7dee39 @isaacs Add npm removal instructions
isaacs authored
144
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
145 To remove cruft left behind by npm 0.x, you can use the included
146 `clean-old.sh` script file. You can run it conveniently like this:
c7dee39 @isaacs Add npm removal instructions
isaacs authored
147
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
148 npm explore npm -g -- sh scripts/clean-old.sh
c7dee39 @isaacs Add npm removal instructions
isaacs authored
149
a26fb09 @isaacs Config removal instructions
isaacs authored
150 npm uses two configuration files, one for per-user configs, and another
151 for global (every-user) configs. You can view them by doing:
152
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
153 npm config get userconfig # defaults to ~/.npmrc
154 npm config get globalconfig # defaults to /usr/local/etc/npmrc
a26fb09 @isaacs Config removal instructions
isaacs authored
155
156 Uninstalling npm does not remove configuration files by default. You
157 must remove them yourself manually if you want them gone. Note that
158 this means that future npm installs will not remember the settings that
159 you have chosen.
160
da8557a @isaacs document programmatic usage
isaacs authored
161 ## Using npm Programmatically
162
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
163 If you would like to use npm programmatically, you can do that.
78a05bb Added syntax highlighting for codeblocks (README.md).
Zearin authored
164 It's not very well documented, but it *is* rather simple.
165
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
166 var npm = require("npm")
167 npm.load(myConfigObject, function (er) {
168 if (er) return handlError(er)
169 npm.commands.install(["some", "args"], function (er, data) {
170 if (er) return commandFailed(er)
171 // command succeeded, and data might have some info
172 })
173 npm.on("log", function (message) { .... })
174 })
da8557a @isaacs document programmatic usage
isaacs authored
175
701a821 @isaacs Confusion about args vs conf
isaacs authored
176 The `load` function takes an object hash of the command-line configs.
177 The various `npm.commands.<cmd>` functions take an **array** of
178 positional argument **strings**. The last argument to any
179 `npm.commands.<cmd>` function is a callback. Some commands take other
180 optional arguments. Read the source.
181
182 You cannot set configs individually for any single npm function at this
183 time. Since `npm` is a singleton, any call to `npm.config.set` will
184 change the value for *all* npm commands in that process.
185
4eb8f6b @isaacs Avoid accidentally opening npm.js with WSH
isaacs authored
186 See `./bin/npm-cli.js` for an example of pulling config values off of the
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
187 command line arguments using nopt. You may also want to check out `npm
188 help config` to learn about all the options you can set there.
266f1c9 @isaacs Update the README with more helpful info.
isaacs authored
189
d9e9c14 @isaacs Point developers to the docs
isaacs authored
190 ## More Docs
191
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
192 Check out the [docs](http://npmjs.org/doc/),
b16093e @isaacs Make readme a bit more accurate
isaacs authored
193 especially the [faq](http://npmjs.org/doc/faq.html).
d9e9c14 @isaacs Point developers to the docs
isaacs authored
194
5e04f23 @isaacs Spruce up the install cmd a bit
isaacs authored
195 You can use the `npm help` command to read any of them.
5885cbf @isaacs Update readme to reference super duper easy install script.
isaacs authored
196
d9e9c14 @isaacs Point developers to the docs
isaacs authored
197 If you're a developer, and you want to use npm to publish your program,
198 you should
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
199 [read this](http://npmjs.org/doc/developers.html)
492dff3 @isaacs README updates. Legalese, proper instructions, etc.
isaacs authored
200
201 ## Legal Stuff
202
203 "npm" and "the npm registry" are owned by Isaac Z. Schlueter. All
204 rights not explicitly granted in the MIT license are reserved. See the
205 included LICENSE file for more details.
206
207 "Node.js" and "node" are trademarks owned by Joyent, Inc. npm is not
208 officially part of the Node.js project, and is neither owned by nor
209 officially affiliated with Joyent, Inc.
210
211 The packages in the npm registry are not part of npm itself, and are the
212 sole property of their respective maintainers. While every effort is
213 made to ensure accountability, there is absolutely no guarantee,
214 warrantee, or assertion made as to the quality, fitness for a specific
215 purpose, or lack of malice in any given npm package. Modules
216 published on the npm registry are not affiliated with or endorsed by
217 Joyent, Inc., Isaac Z. Schlueter, Ryan Dahl, or the Node.js project.
218
219 If you have a complaint about a package in the npm registry, and cannot
220 resolve it with the package owner, please express your concerns to
221 Isaac Z. Schlueter at <i@izs.me>.
222
223 ### In plain english
224
225 This is mine; not my employer's, not Node's, not Joyent's, not Ryan
226 Dahl's.
227
228 If you publish something, it's yours, and you are solely accountable
229 for it. Not me, not Node, not Joyent, not Ryan Dahl.
230
231 If other people publish something, it's theirs. Not mine, not Node's,
232 not Joyent's, not Ryan Dahl's.
233
234 Yes, you can publish something evil. It will be removed promptly if
235 reported, and we'll lose respect for you. But there is no vetting
236 process for published modules.
237
238 If this concerns you, inspect the source before using packages.
32f2673 @isaacs Add README as proper html/manpage doc
isaacs authored
239
b16093e @isaacs Make readme a bit more accurate
isaacs authored
240 ## BUGS
241
242 When you find issues, please report them:
243
244 * web:
245 <http://github.com/isaacs/npm/issues>
246 * email:
247 <npm-@googlegroups.com>
248
249 Be sure to include *all* of the output from the npm command that didn't work
250 as expected. The `npm-debug.log` file is also helpful to provide.
251
252 You can also look for isaacs in #node.js on irc://irc.freenode.net. He
253 will no doubt tell you to put the output in a gist or email.
254
32f2673 @isaacs Add README as proper html/manpage doc
isaacs authored
255 ## SEE ALSO
256
257 * npm(1)
258 * npm-faq(1)
259 * npm-help(1)
4dc1095 @isaacs Add some see-also links to npm-index(1)
isaacs authored
260 * npm-index(1)
Something went wrong with that request. Please try again.