Skip to content

HTTPS clone URL

Subversion checkout URL

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