Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

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