Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 191 lines (124 sloc) 5.983 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
266f1c9 isaacs Update the README with more helpful info.
isaacs authored
15 ## IMPORTANT
16
ac13b34 isaacs Update about node versions
isaacs authored
17 **You need node v0.4 or higher to run this program.**
266f1c9 isaacs Update the README with more helpful info.
isaacs authored
18
ac13b34 isaacs Update about node versions
isaacs authored
19 To install on older versions of node, do the following:
20
21 git clone git://github.com/isaacs/npm.git ./npm
22 cd npm
8ee3c3e isaacs Closes GH-623 correct branch checkout instruction
isaacs authored
23 git checkout origin/0.2
ac13b34 isaacs Update about node versions
isaacs authored
24 make dev
266f1c9 isaacs Update the README with more helpful info.
isaacs authored
25
069a27c isaacs Add a simpler install process up near the top.
isaacs authored
26 ## Simple Install
841f3b5 isaacs Move the installing section up to the top
isaacs authored
27
5e04f23 isaacs Spruce up the install cmd a bit
isaacs authored
28 To install npm with one command, do this:
d49a887 isaacs add some more installation suggestions/options
isaacs authored
29
5d212a7 isaacs update readme for 1.0
isaacs authored
30 curl http://npmjs.org/install.sh | npm_install=rc sh
d49a887 isaacs add some more installation suggestions/options
isaacs authored
31
5d6fb4b isaacs the install script sometimes fails.
isaacs authored
32 If that fails, try this:
33
34 git clone http://github.com/isaacs/npm.git
35 cd npm
678d2e8 isaacs change readme to suggest root usage
isaacs authored
36 sudo make install
5d6fb4b isaacs the install script sometimes fails.
isaacs authored
37
5e04f23 isaacs Spruce up the install cmd a bit
isaacs authored
38 If you're sitting in the code folder reading this document in your
39 terminal, then you've already got the code. Just do:
40
678d2e8 isaacs change readme to suggest root usage
isaacs authored
41 sudo make install
5e04f23 isaacs Spruce up the install cmd a bit
isaacs authored
42
43 and npm will install itself.
44
45 If you don't have make, and don't have curl or git, and ALL you have is
46 this code and node, you can do:
47
5d212a7 isaacs update readme for 1.0
isaacs authored
48 sudo node ./cli.js install -g
57729b7 isaacs Documentation updates
isaacs authored
49
678d2e8 isaacs change readme to suggest root usage
isaacs authored
50 ## Permissions
0164a0d isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
51
8ee3c3e isaacs Closes GH-623 correct branch checkout instruction
isaacs authored
52 **tl;dr**
53
54 * Use `sudo` for greater safety.
55 * To enforce this added safety, do `npm config set unsafe-perm false`,
56 or add `--no-unsafe` to the command line.
57 * npm will downgrade permissions if it's root before running any build
58 scripts that package authors specified.
59 * If you were fine before, you can safely ignore this change.
0164a0d isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
60
678d2e8 isaacs change readme to suggest root usage
isaacs authored
61 ### More details...
0164a0d isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
62
678d2e8 isaacs change readme to suggest root usage
isaacs authored
63 As of version 0.3, it is recommended to run some npm commands as root.
64 This allows npm to change the user identifier to the `nobody` user prior
65 to running any package build or test commands.
3901ac1 isaacs Be more specific with the chown instructions
isaacs authored
66
678d2e8 isaacs change readme to suggest root usage
isaacs authored
67 If this user id switch fails (generally because you are not the root
68 user) then the command will fail.
0164a0d isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
69
678d2e8 isaacs change readme to suggest root usage
isaacs authored
70 If you would prefer to run npm as your own user, giving package scripts
71 the same rights that your user account enjoys, then you may do so by
72 setting the `unsafe-perm` config value to `true`:
0164a0d isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
73
678d2e8 isaacs change readme to suggest root usage
isaacs authored
74 npm config set unsafe-perm true
0164a0d isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
75
678d2e8 isaacs change readme to suggest root usage
isaacs authored
76 or simply by setting the `--unsafe` flag to any individual command:
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 test express --unsafe
0164a0d isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
79
80
678d2e8 isaacs change readme to suggest root usage
isaacs authored
81 Note that root/sudo access is only required when npm is doing the
82 following actions:
0164a0d isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
83
678d2e8 isaacs change readme to suggest root usage
isaacs authored
84 1. Writing files and folders to the root.
85 2. Running package lifecycle scripts (generally to either build or
86 test).
0164a0d isaacs Make the "don't use sudo" explanation clearer.
isaacs authored
87
678d2e8 isaacs change readme to suggest root usage
isaacs authored
88 If you run npm without root privileges, and it doesn't have to do either
89 of these things, then no error will occur.
d49a887 isaacs add some more installation suggestions/options
isaacs authored
90
678d2e8 isaacs change readme to suggest root usage
isaacs authored
91 npm will automatically attempt to escalate permissions (generally by
92 prompting for your password) if it attempts to *remove* a file and fails
93 with an EPERM or EACCES error. No other permission escalation is
94 attempted.
61fea1c isaacs Make the .npmrc sample more clear, and add some words about sudoing
isaacs authored
95
678d2e8 isaacs change readme to suggest root usage
isaacs authored
96 This is a departure from npm's history, and comes at long last.
61fea1c isaacs Make the .npmrc sample more clear, and add some words about sudoing
isaacs authored
97
069a27c isaacs Add a simpler install process up near the top.
isaacs authored
98 ## More Fancy Installing
99
100 First, get the code. Maybe use git for this. That'd be cool. Very fancy.
101
bf84068 isaacs update make stuff in the README
isaacs authored
102 The default make target is `install`, which downloads the current stable
895281c isaacs Update install instructions.
isaacs authored
103 version of npm, and installs that for you.
069a27c isaacs Add a simpler install process up near the top.
isaacs authored
104
895281c isaacs Update install instructions.
isaacs authored
105 If you want to install the exact code that you're looking at, the bleeding-edge
106 master branch, do this:
107
678d2e8 isaacs change readme to suggest root usage
isaacs authored
108 sudo make dev
069a27c isaacs Add a simpler install process up near the top.
isaacs authored
109
110 If you'd prefer to just symlink in the current code so you can hack
111 on it, you can do this:
112
678d2e8 isaacs change readme to suggest root usage
isaacs authored
113 sudo make link
895281c isaacs Update install instructions.
isaacs authored
114
115 If you check out the Makefile, you'll see that these are just running npm commands
116 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
117 it by using `node cli.js` instead of "npm". Set up an alias if you want, that's
118 fine. (You'll still need read permission to the root/binroot/manroot folders,
119 but at this point, you probably grok all that anyway.)
069a27c isaacs Add a simpler install process up near the top.
isaacs authored
120
c71ae65 isaacs version notes for 0.1.11
isaacs authored
121 ## Uninstalling
122
123 So sad to see you go.
124
5d212a7 isaacs update readme for 1.0
isaacs authored
125 sudo npm uninstall npm -g
c71ae65 isaacs version notes for 0.1.11
isaacs authored
126
127 Or, if that fails,
128
678d2e8 isaacs change readme to suggest root usage
isaacs authored
129 sudo make uninstall
d9e9c14 isaacs Point developers to the docs
isaacs authored
130
c7dee39 isaacs Add npm removal instructions
isaacs authored
131 ## More Severe Uninstalling
132
133 Usually, the above instructions are sufficient. That will remove
134 npm, but leave behind anything you've installed.
135
136 If that doesn't work, or if you require more drastic measures,
137 continue reading.
138
139 This assumes that you installed node and npm in the default place. If
140 you configured node with a different `--prefix`, or installed npm with a
141 different prefix setting, then adjust the paths accordingly, replacing
142 `/usr/local` with your install prefix.
143
144 rm -rf /usr/local/{lib/node,lib/node/.npm,bin,share/man}/npm*
145
146 If you installed things *with* npm, then your best bet is to uninstall
147 them with npm first, and then install them again once you have a
148 proper install. This can help find any symlinks that are lying
149 around:
150
151 ls -laF /usr/local/{lib/node,lib/node/.npm,bin,share/man} | grep npm
152
153 Prior to version 0.3, npm used shim files for executables and node
154 modules. To track those down, you can do the following:
155
156 find /usr/local/{lib/node,bin} -exec grep -l npm \{\} \; ;
157
da8557a isaacs document programmatic usage
isaacs authored
158 ## Using npm Programmatically
159
160 If you would like to use npm programmatically, you can do that as of
161 version 0.2.6. It's not very well documented, but it IS rather simple.
162
163 var npm = require("npm")
164 npm.load(myConfigObject, function (er) {
165 if (er) return handlError(er)
166 npm.commands.install(["some", "args"], function (er, data) {
167 if (er) return commandFailed(er)
168 // command succeeded, and data might have some info
169 })
170 npm.on("log", function (message) { .... })
171 })
172
173 See `./cli.js` for an example of pulling config values off of the
174 command line arguments. You may also want to check out `npm help
175 config` to learn about all the options you can set there.
176
177 As more features are added for programmatic access to the npm library,
178 this section will likely be split out into its own documentation page.
266f1c9 isaacs Update the README with more helpful info.
isaacs authored
179
d9e9c14 isaacs Point developers to the docs
isaacs authored
180 ## More Docs
181
5e04f23 isaacs Spruce up the install cmd a bit
isaacs authored
182 Check out the [docs](http://github.com/isaacs/npm/blob/master/doc/),
183 especially the
184 [faq](http://github.com/isaacs/npm/blob/master/doc/faq.md#readme).
d9e9c14 isaacs Point developers to the docs
isaacs authored
185
5e04f23 isaacs Spruce up the install cmd a bit
isaacs authored
186 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
187
d9e9c14 isaacs Point developers to the docs
isaacs authored
188 If you're a developer, and you want to use npm to publish your program,
189 you should
190 [read this](http://github.com/isaacs/npm/blob/master/doc/developers.md#readme)
Something went wrong with that request. Please try again.