Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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