Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 227 lines (149 sloc) 7.404 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
e5bfb0c isaacs Add note about 1.0
isaacs authored
7 ## RELEASE CANDIDATE
8
9 The master branch contains the latest release candidate, which as of
10 this time is 1.0.something. If you want version 0.2 or 0.3, then you'll
11 need to check those branches out explicitly.
12
13 The "latest" on the registry is 0.3, because 1.0 is not yet stable.
14
492dff3 isaacs README updates. Legalese, proper instructions, etc.
isaacs authored
15 It will be the default install target at the end of April, 2011.
16
266f1c9 isaacs Update the README with more helpful info.
isaacs authored
17 ## IMPORTANT
18
ac13b34 isaacs Update about node versions
isaacs authored
19 **You need node v0.4 or higher to run this program.**
266f1c9 isaacs Update the README with more helpful info.
isaacs authored
20
492dff3 isaacs README updates. Legalese, proper instructions, etc.
isaacs authored
21 To install an old **and unsupported** version of npm that works on node 0.3
22 and prior:
ac13b34 isaacs Update about node versions
isaacs authored
23
24 git clone git://github.com/isaacs/npm.git ./npm
25 cd npm
8ee3c3e isaacs Closes GH-623 correct branch checkout instruction
isaacs authored
26 git checkout origin/0.2
ac13b34 isaacs Update about node versions
isaacs authored
27 make dev
266f1c9 isaacs Update the README with more helpful info.
isaacs authored
28
069a27c isaacs Add a simpler install process up near the top.
isaacs authored
29 ## Simple Install
841f3b5 isaacs Move the installing section up to the top
isaacs authored
30
5e04f23 isaacs Spruce up the install cmd a bit
isaacs authored
31 To install npm with one command, do this:
d49a887 isaacs add some more installation suggestions/options
isaacs authored
32
5d212a7 isaacs update readme for 1.0
isaacs authored
33 curl http://npmjs.org/install.sh | npm_install=rc sh
d49a887 isaacs add some more installation suggestions/options
isaacs authored
34
5d6fb4b isaacs the install script sometimes fails.
isaacs authored
35 If that fails, try this:
36
37 git clone http://github.com/isaacs/npm.git
38 cd npm
678d2e8 isaacs change readme to suggest root usage
isaacs authored
39 sudo make install
5d6fb4b isaacs the install script sometimes fails.
isaacs authored
40
5e04f23 isaacs Spruce up the install cmd a bit
isaacs authored
41 If you're sitting in the code folder reading this document in your
42 terminal, then you've already got the code. Just do:
43
678d2e8 isaacs change readme to suggest root usage
isaacs authored
44 sudo make install
5e04f23 isaacs Spruce up the install cmd a bit
isaacs authored
45
46 and npm will install itself.
47
48 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
49 this code and node, you can probably do this:
5e04f23 isaacs Spruce up the install cmd a bit
isaacs authored
50
5d212a7 isaacs update readme for 1.0
isaacs authored
51 sudo node ./cli.js install -g
57729b7 isaacs Documentation updates
isaacs authored
52
492dff3 isaacs README updates. Legalese, proper instructions, etc.
isaacs authored
53 However, note that github tarballs **do not contain submodules**, so
54 those won't work. You'll have to also fetch the appropriate submodules
55 listed in the .gitmodules file.
56
678d2e8 isaacs change readme to suggest root usage
isaacs authored
57 ## Permissions
0164a0d isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
58
8ee3c3e isaacs Closes GH-623 correct branch checkout instruction
isaacs authored
59 **tl;dr**
60
492dff3 isaacs README updates. Legalese, proper instructions, etc.
isaacs authored
61 * Use `sudo` for greater safety. Or don't.
8ee3c3e isaacs Closes GH-623 correct branch checkout instruction
isaacs authored
62 * npm will downgrade permissions if it's root before running any build
63 scripts that package authors specified.
0164a0d isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
64
678d2e8 isaacs change readme to suggest root usage
isaacs authored
65 ### More details...
0164a0d isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
66
678d2e8 isaacs change readme to suggest root usage
isaacs authored
67 As of version 0.3, it is recommended to run some npm commands as root.
68 This allows npm to change the user identifier to the `nobody` user prior
69 to running any package build or test commands.
3901ac1 isaacs Be more specific with the chown instructions
isaacs authored
70
678d2e8 isaacs change readme to suggest root usage
isaacs authored
71 If this user id switch fails (generally because you are not the root
72 user) then the command will fail.
0164a0d isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
73
678d2e8 isaacs change readme to suggest root usage
isaacs authored
74 If you would prefer to run npm as your own user, giving package scripts
75 the same rights that your user account enjoys, then you may do so by
76 setting the `unsafe-perm` config value to `true`:
0164a0d isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
77
678d2e8 isaacs change readme to suggest root usage
isaacs authored
78 npm config set unsafe-perm true
0164a0d isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
79
678d2e8 isaacs change readme to suggest root usage
isaacs authored
80 or simply by setting the `--unsafe` flag to any individual command:
0164a0d isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
81
678d2e8 isaacs change readme to suggest root usage
isaacs authored
82 npm test express --unsafe
0164a0d isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
83
84
678d2e8 isaacs change readme to suggest root usage
isaacs authored
85 Note that root/sudo access is only required when npm is doing the
86 following actions:
0164a0d isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
87
678d2e8 isaacs change readme to suggest root usage
isaacs authored
88 1. Writing files and folders to the root.
89 2. Running package lifecycle scripts (generally to either build or
90 test).
0164a0d isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
91
678d2e8 isaacs change readme to suggest root usage
isaacs authored
92 If you run npm without root privileges, and it doesn't have to do either
93 of these things, then no error will occur.
d49a887 isaacs add some more installation suggestions/options
isaacs authored
94
069a27c isaacs Add a simpler install process up near the top.
isaacs authored
95 ## More Fancy Installing
96
97 First, get the code. Maybe use git for this. That'd be cool. Very fancy.
98
bf84068 isaacs update make stuff in the README
isaacs authored
99 The default make target is `install`, which downloads the current stable
895281c isaacs Update install instructions.
isaacs authored
100 version of npm, and installs that for you.
069a27c isaacs Add a simpler install process up near the top.
isaacs authored
101
895281c isaacs Update install instructions.
isaacs authored
102 If you want to install the exact code that you're looking at, the bleeding-edge
103 master branch, do this:
104
678d2e8 isaacs change readme to suggest root usage
isaacs authored
105 sudo make dev
069a27c isaacs Add a simpler install process up near the top.
isaacs authored
106
107 If you'd prefer to just symlink in the current code so you can hack
108 on it, you can do this:
109
678d2e8 isaacs change readme to suggest root usage
isaacs authored
110 sudo make link
895281c isaacs Update install instructions.
isaacs authored
111
112 If you check out the Makefile, you'll see that these are just running npm commands
113 at the cli.js script directly. You can also use npm without ever installing
266f1c9 isaacs Update the README with more helpful info.
isaacs authored
114 it by using `node cli.js` instead of "npm". Set up an alias if you want, that's
115 fine. (You'll still need read permission to the root/binroot/manroot folders,
116 but at this point, you probably grok all that anyway.)
069a27c isaacs Add a simpler install process up near the top.
isaacs authored
117
c71ae65 isaacs version notes for 0.1.11
isaacs authored
118 ## Uninstalling
119
120 So sad to see you go.
121
5d212a7 isaacs update readme for 1.0
isaacs authored
122 sudo npm uninstall npm -g
c71ae65 isaacs version notes for 0.1.11
isaacs authored
123
124 Or, if that fails,
125
678d2e8 isaacs change readme to suggest root usage
isaacs authored
126 sudo make uninstall
d9e9c14 isaacs Point developers to the docs
isaacs authored
127
c7dee39 isaacs Add npm removal instructions
isaacs authored
128 ## More Severe Uninstalling
129
130 Usually, the above instructions are sufficient. That will remove
131 npm, but leave behind anything you've installed.
132
133 If that doesn't work, or if you require more drastic measures,
134 continue reading.
135
136 This assumes that you installed node and npm in the default place. If
137 you configured node with a different `--prefix`, or installed npm with a
138 different prefix setting, then adjust the paths accordingly, replacing
139 `/usr/local` with your install prefix.
140
141 rm -rf /usr/local/{lib/node,lib/node/.npm,bin,share/man}/npm*
142
143 If you installed things *with* npm, then your best bet is to uninstall
144 them with npm first, and then install them again once you have a
145 proper install. This can help find any symlinks that are lying
146 around:
147
148 ls -laF /usr/local/{lib/node,lib/node/.npm,bin,share/man} | grep npm
149
150 Prior to version 0.3, npm used shim files for executables and node
151 modules. To track those down, you can do the following:
152
153 find /usr/local/{lib/node,bin} -exec grep -l npm \{\} \; ;
154
da8557a isaacs document programmatic usage
isaacs authored
155 ## Using npm Programmatically
156
157 If you would like to use npm programmatically, you can do that as of
158 version 0.2.6. It's not very well documented, but it IS rather simple.
159
160 var npm = require("npm")
161 npm.load(myConfigObject, function (er) {
162 if (er) return handlError(er)
163 npm.commands.install(["some", "args"], function (er, data) {
164 if (er) return commandFailed(er)
165 // command succeeded, and data might have some info
166 })
167 npm.on("log", function (message) { .... })
168 })
169
170 See `./cli.js` for an example of pulling config values off of the
171 command line arguments. You may also want to check out `npm help
172 config` to learn about all the options you can set there.
173
174 As more features are added for programmatic access to the npm library,
175 this section will likely be split out into its own documentation page.
266f1c9 isaacs Update the README with more helpful info.
isaacs authored
176
d9e9c14 isaacs Point developers to the docs
isaacs authored
177 ## More Docs
178
5e04f23 isaacs Spruce up the install cmd a bit
isaacs authored
179 Check out the [docs](http://github.com/isaacs/npm/blob/master/doc/),
180 especially the
181 [faq](http://github.com/isaacs/npm/blob/master/doc/faq.md#readme).
d9e9c14 isaacs Point developers to the docs
isaacs authored
182
5e04f23 isaacs Spruce up the install cmd a bit
isaacs authored
183 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
184
d9e9c14 isaacs Point developers to the docs
isaacs authored
185 If you're a developer, and you want to use npm to publish your program,
186 you should
187 [read this](http://github.com/isaacs/npm/blob/master/doc/developers.md#readme)
492dff3 isaacs README updates. Legalese, proper instructions, etc.
isaacs authored
188
189 ## Legal Stuff
190
191 "npm" and "the npm registry" are owned by Isaac Z. Schlueter. All
192 rights not explicitly granted in the MIT license are reserved. See the
193 included LICENSE file for more details.
194
195 "Node.js" and "node" are trademarks owned by Joyent, Inc. npm is not
196 officially part of the Node.js project, and is neither owned by nor
197 officially affiliated with Joyent, Inc.
198
199 The packages in the npm registry are not part of npm itself, and are the
200 sole property of their respective maintainers. While every effort is
201 made to ensure accountability, there is absolutely no guarantee,
202 warrantee, or assertion made as to the quality, fitness for a specific
203 purpose, or lack of malice in any given npm package. Modules
204 published on the npm registry are not affiliated with or endorsed by
205 Joyent, Inc., Isaac Z. Schlueter, Ryan Dahl, or the Node.js project.
206
207 If you have a complaint about a package in the npm registry, and cannot
208 resolve it with the package owner, please express your concerns to
209 Isaac Z. Schlueter at <i@izs.me>.
210
211 ### In plain english
212
213 This is mine; not my employer's, not Node's, not Joyent's, not Ryan
214 Dahl's.
215
216 If you publish something, it's yours, and you are solely accountable
217 for it. Not me, not Node, not Joyent, not Ryan Dahl.
218
219 If other people publish something, it's theirs. Not mine, not Node's,
220 not Joyent's, not Ryan Dahl's.
221
222 Yes, you can publish something evil. It will be removed promptly if
223 reported, and we'll lose respect for you. But there is no vetting
224 process for published modules.
225
226 If this concerns you, inspect the source before using packages.
Something went wrong with that request. Please try again.