Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 210 lines (139 sloc) 6.873 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
ac13b34 @isaacs Update about node versions
isaacs authored
12 **You need node v0.4 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
069a27c @isaacs Add a simpler install process up near the top.
isaacs authored
17 ## Simple Install
841f3b5 @isaacs Move the installing section up to the top
isaacs authored
18
5e04f23 @isaacs Spruce up the install cmd a bit
isaacs authored
19 To install npm with one command, do this:
d49a887 @isaacs add some more installation suggestions/options
isaacs authored
20
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
21 curl http://npmjs.org/install.sh | sh
d49a887 @isaacs add some more installation suggestions/options
isaacs authored
22
36b4215 @isaacs Add clean=yes/no instructions to README
isaacs authored
23 To skip the npm 0.x cleanup, do this:
24
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
25 curl http://npmjs.org/install.sh | clean=no sh
36b4215 @isaacs Add clean=yes/no instructions to README
isaacs authored
26
27 To say "yes" to the 0.x cleanup, but skip the prompt:
28
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
29 curl http://npmjs.org/install.sh | clean=yes sh
36b4215 @isaacs Add clean=yes/no instructions to README
isaacs authored
30
6740f2a @isaacs Add 'curl|sudo sh' instructions
isaacs authored
31 If you get permission errors, you can either install node someplace that
32 you have permission to write to (recommended!) or you *can* place a **very
33 unsafe amount of trust** in me, and in your network, and do this:
34
35 curl http://npmjs.org/install.sh | sudo sh
36
37 **Note**: You need to `sudo` the `sh`, **not** the `curl`. Fetching stuff
38 from the internet typically doesn't require elevated permissions.
39
40 ## Dev Install
41
42 To install the latest **unstable** development version from git:
5d6fb4b @isaacs the install script sometimes fails.
isaacs authored
43
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
44 git clone https://github.com/isaacs/npm.git
45 cd npm
46 sudo make install
5d6fb4b @isaacs the install script sometimes fails.
isaacs authored
47
5e04f23 @isaacs Spruce up the install cmd a bit
isaacs authored
48 If you're sitting in the code folder reading this document in your
49 terminal, then you've already got the code. Just do:
50
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
51 sudo make install
5e04f23 @isaacs Spruce up the install cmd a bit
isaacs authored
52
53 and npm will install itself.
54
55 If you don't have make, and don't have curl or git, and ALL you have is
492dff3 @isaacs README updates. Legalese, proper instructions, etc.
isaacs authored
56 this code and node, you can probably do this:
5e04f23 @isaacs Spruce up the install cmd a bit
isaacs authored
57
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
58 sudo node ./cli.js install -g
57729b7 @isaacs Documentation updates
isaacs authored
59
492dff3 @isaacs README updates. Legalese, proper instructions, etc.
isaacs authored
60 However, note that github tarballs **do not contain submodules**, so
61 those won't work. You'll have to also fetch the appropriate submodules
62 listed in the .gitmodules file.
63
678d2e8 @isaacs change readme to suggest root usage
isaacs authored
64 ## Permissions
0164a0d @isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
65
8ee3c3e @isaacs Closes GH-623 correct branch checkout instruction
isaacs authored
66 **tl;dr**
67
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
68 * Use `sudo` for greater safety. Or don't, if you prefer not to.
8ee3c3e @isaacs Closes GH-623 correct branch checkout instruction
isaacs authored
69 * npm will downgrade permissions if it's root before running any build
70 scripts that package authors specified.
0164a0d @isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
71
678d2e8 @isaacs change readme to suggest root usage
isaacs authored
72 ### More details...
0164a0d @isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
73
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
74 As of version 0.3, it is recommended to run npm as root.
678d2e8 @isaacs change readme to suggest root usage
isaacs authored
75 This allows npm to change the user identifier to the `nobody` user prior
76 to running any package build or test commands.
3901ac1 @isaacs Be more specific with the chown instructions
isaacs authored
77
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
78 If you are not the root user, or if you are on a platform that does not
79 support uid switching, then npm will not attempt to change the userid.
0164a0d @isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
80
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
81 If you would like to ensure that npm **always** runs scripts as the
82 "nobody" user, and have it fail if it cannot downgrade permissions, then
83 set the following configuration param:
d49a887 @isaacs add some more installation suggestions/options
isaacs authored
84
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
85 npm config set unsafe-perm false
069a27c @isaacs Add a simpler install process up near the top.
isaacs authored
86
78a05bb Added syntax highlighting for codeblocks (README.md).
Zearin authored
87 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
88
c71ae65 @isaacs version notes for 0.1.11
isaacs authored
89 ## Uninstalling
90
91 So sad to see you go.
92
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
93 sudo npm uninstall npm -g
c71ae65 @isaacs version notes for 0.1.11
isaacs authored
94
95 Or, if that fails,
96
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
97 sudo make uninstall
d9e9c14 @isaacs Point developers to the docs
isaacs authored
98
c7dee39 @isaacs Add npm removal instructions
isaacs authored
99 ## More Severe Uninstalling
100
101 Usually, the above instructions are sufficient. That will remove
102 npm, but leave behind anything you've installed.
103
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
104 If you would like to remove all the packages that you have installed,
105 then you can use the `npm ls` command to find them, and then `npm rm` to
106 remove them.
c7dee39 @isaacs Add npm removal instructions
isaacs authored
107
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
108 To remove cruft left behind by npm 0.x, you can use the included
109 `clean-old.sh` script file. You can run it conveniently like this:
c7dee39 @isaacs Add npm removal instructions
isaacs authored
110
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
111 npm explore npm -g -- sh scripts/clean-old.sh
c7dee39 @isaacs Add npm removal instructions
isaacs authored
112
a26fb09 @isaacs Config removal instructions
isaacs authored
113 npm uses two configuration files, one for per-user configs, and another
114 for global (every-user) configs. You can view them by doing:
115
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
116 npm config get userconfig # defaults to ~/.npmrc
117 npm config get globalconfig # defaults to /usr/local/etc/npmrc
a26fb09 @isaacs Config removal instructions
isaacs authored
118
119 Uninstalling npm does not remove configuration files by default. You
120 must remove them yourself manually if you want them gone. Note that
121 this means that future npm installs will not remember the settings that
122 you have chosen.
123
da8557a @isaacs document programmatic usage
isaacs authored
124 ## Using npm Programmatically
125
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
126 If you would like to use npm programmatically, you can do that.
78a05bb Added syntax highlighting for codeblocks (README.md).
Zearin authored
127 It's not very well documented, but it *is* rather simple.
128
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
129 var npm = require("npm")
130 npm.load(myConfigObject, function (er) {
131 if (er) return handlError(er)
132 npm.commands.install(["some", "args"], function (er, data) {
133 if (er) return commandFailed(er)
134 // command succeeded, and data might have some info
135 })
136 npm.on("log", function (message) { .... })
137 })
da8557a @isaacs document programmatic usage
isaacs authored
138
701a821 @isaacs Confusion about args vs conf
isaacs authored
139 The `load` function takes an object hash of the command-line configs.
140 The various `npm.commands.<cmd>` functions take an **array** of
141 positional argument **strings**. The last argument to any
142 `npm.commands.<cmd>` function is a callback. Some commands take other
143 optional arguments. Read the source.
144
145 You cannot set configs individually for any single npm function at this
146 time. Since `npm` is a singleton, any call to `npm.config.set` will
147 change the value for *all* npm commands in that process.
148
dafc7d0 @isaacs correct readme for 1.0
isaacs authored
149 See `./bin/npm.js` for an example of pulling config values off of the
150 command line arguments using nopt. You may also want to check out `npm
151 help config` to learn about all the options you can set there.
266f1c9 @isaacs Update the README with more helpful info.
isaacs authored
152
d9e9c14 @isaacs Point developers to the docs
isaacs authored
153 ## More Docs
154
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
155 Check out the [docs](http://npmjs.org/doc/),
5e04f23 @isaacs Spruce up the install cmd a bit
isaacs authored
156 especially the
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
157 [faq](http://npmjs.org/doc/faq.html).
d9e9c14 @isaacs Point developers to the docs
isaacs authored
158
5e04f23 @isaacs Spruce up the install cmd a bit
isaacs authored
159 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
160
d9e9c14 @isaacs Point developers to the docs
isaacs authored
161 If you're a developer, and you want to use npm to publish your program,
162 you should
ec66825 @isaacs Fold the README into the html doc build
isaacs authored
163 [read this](http://npmjs.org/doc/developers.html)
492dff3 @isaacs README updates. Legalese, proper instructions, etc.
isaacs authored
164
165 ## Legal Stuff
166
167 "npm" and "the npm registry" are owned by Isaac Z. Schlueter. All
168 rights not explicitly granted in the MIT license are reserved. See the
169 included LICENSE file for more details.
170
171 "Node.js" and "node" are trademarks owned by Joyent, Inc. npm is not
172 officially part of the Node.js project, and is neither owned by nor
173 officially affiliated with Joyent, Inc.
174
175 The packages in the npm registry are not part of npm itself, and are the
176 sole property of their respective maintainers. While every effort is
177 made to ensure accountability, there is absolutely no guarantee,
178 warrantee, or assertion made as to the quality, fitness for a specific
179 purpose, or lack of malice in any given npm package. Modules
180 published on the npm registry are not affiliated with or endorsed by
181 Joyent, Inc., Isaac Z. Schlueter, Ryan Dahl, or the Node.js project.
182
183 If you have a complaint about a package in the npm registry, and cannot
184 resolve it with the package owner, please express your concerns to
185 Isaac Z. Schlueter at <i@izs.me>.
186
187 ### In plain english
188
189 This is mine; not my employer's, not Node's, not Joyent's, not Ryan
190 Dahl's.
191
192 If you publish something, it's yours, and you are solely accountable
193 for it. Not me, not Node, not Joyent, not Ryan Dahl.
194
195 If other people publish something, it's theirs. Not mine, not Node's,
196 not Joyent's, not Ryan Dahl's.
197
198 Yes, you can publish something evil. It will be removed promptly if
199 reported, and we'll lose respect for you. But there is no vetting
200 process for published modules.
201
202 If this concerns you, inspect the source before using packages.
32f2673 @isaacs Add README as proper html/manpage doc
isaacs authored
203
204 ## SEE ALSO
205
206 * npm(1)
207 * npm-faq(1)
208 * npm-help(1)
4dc1095 @isaacs Add some see-also links to npm-index(1)
isaacs authored
209 * npm-index(1)
Something went wrong with that request. Please try again.