4 An NPM installer for [PhantomJS](http://phantomjs.org/), headless webkit with JS API.
6 [![Build Status](https://travis-ci.org/Medium/phantomjs.svg?branch=master)](https://travis-ci.org/Medium/phantomjs)
8 Building and Installing
9 -----------------------
12 npm install phantomjs-prebuilt
15 Or grab the source and
21 What this installer is really doing is just grabbing a particular "blessed" (by
22 this module) version of Phantom. As new versions of Phantom are released
23 and vetted, this module will be updated accordingly.
29 bin/phantomjs [phantom arguments]
32 And npm will install a link to the binary in `node_modules/.bin` as
38 The package exports a `path` string that contains the path to the
39 phantomjs binary/executable.
41 Below is an example of using this package via node.
44 var path = require('path')
45 var childProcess = require('child_process')
46 var phantomjs = require('phantomjs-prebuilt')
47 var binPath = phantomjs.path
50 path.join(__dirname, 'phantomjs-script.js'),
51 'some other argument (passed to phantomjs script)'
54 childProcess.execFile(binPath, childArgs, function(err, stdout, stderr) {
60 Or `exec()` method is also provided for convenience:
63 var phantomjs = require('phantomjs-prebuilt')
64 var program = phantomjs.exec('phantomjs-script.js', 'arg1', 'arg2')
65 program.stdout.pipe(process.stdout)
66 program.stderr.pipe(process.stderr)
67 program.on('exit', code => {
68 // do something on end
72 Note: [childProcess.spawn()](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) is called inside `exec()`.
74 Running with WebDriver
75 ----------------------
77 `run()` method detects when PhantomJS gets ready. It's handy to use with WebDriver (Selenium).
80 var phantomjs = require('phantomjs-prebuilt')
81 var webdriverio = require('webdriverio')
82 var wdOpts = { desiredCapabilities: { browserName: 'phantomjs' } }
84 phantomjs.run('--webdriver=4444').then(program => {
85 webdriverio.remote(wdOpts).init()
86 .url('https://developer.mozilla.org/en-US/')
87 .getTitle().then(title => {
88 console.log(title) // 'Mozilla Developer Network'
89 program.kill() // quits PhantomJS
97 The major and minor number tracks the version of PhantomJS that will be
98 installed. The patch number is incremented when there is either an installer
99 update or a patch build of the phantom binary.
101 Pre-2.0, this package was published to NPM as [phantomjs](https://www.npmjs.com/package/phantomjs).
102 We changed the name to [phantomjs-prebuilt](https://www.npmjs.com/package/phantomjs-prebuilt) at
103 the request of PhantomJS team.
105 Continuous Integration
106 ----------------------
108 Please **do not** download PhantomJS for every CI job because it can quickly
109 overload our CDNs. Instead take advantage of CI caching.
111 In [Travis-CI](https://travis-ci.org/) add the following to your `.travis.yml`
112 to [enable caching](https://docs.travis-ci.com/user/caching/) & avoid repeated
113 downloads of PhantomJS.
122 # Upgrade PhantomJS to v2.1.1.
123 - "export PHANTOMJS_VERSION=2.1.1"
124 - "export PATH=$PWD/travis_phantomjs/phantomjs-$PHANTOMJS_VERSION-linux-x86_64/bin:$PATH"
125 - "if [ $(phantomjs --version) != $PHANTOMJS_VERSION ]; then rm -rf $PWD/travis_phantomjs; mkdir -p $PWD/travis_phantomjs; fi"
126 - "if [ $(phantomjs --version) != $PHANTOMJS_VERSION ]; then wget https://github.com/Medium/phantomjs/releases/download/v$PHANTOMJS_VERSION/phantomjs-$PHANTOMJS_VERSION-linux-x86_64.tar.bz2 -O $PWD/travis_phantomjs/phantomjs-$PHANTOMJS_VERSION-linux-x86_64.tar.bz2; fi"
127 - "if [ $(phantomjs --version) != $PHANTOMJS_VERSION ]; then tar -xvf $PWD/travis_phantomjs/phantomjs-$PHANTOMJS_VERSION-linux-x86_64.tar.bz2 -C $PWD/travis_phantomjs; fi"
128 - "phantomjs --version"
131 Deciding Where To Get PhantomJS
132 -------------------------------
134 By default, this package will download phantomjs from our [releases](https://github.com/Medium/phantomjs/releases/).
135 This should work fine for most people.
137 ##### Downloading from a custom URL
139 If github is down, or the Great Firewall is blocking github, you may need to use
140 a different download mirror. To set a mirror, set npm config property `phantomjs_cdnurl`.
142 Alternatives include `https://bitbucket.org/ariya/phantomjs/downloads` (the official download site)
143 and `http://cnpmjs.org/downloads`.
146 npm install phantomjs-prebuilt --phantomjs_cdnurl=https://bitbucket.org/ariya/phantomjs/downloads
149 Or add property into your `.npmrc` file (https://www.npmjs.org/doc/files/npmrc.html)
152 phantomjs_cdnurl=https://bitbucket.org/ariya/phantomjs/downloads
155 Another option is to use PATH variable `PHANTOMJS_CDNURL`.
157 PHANTOMJS_CDNURL=https://bitbucket.org/ariya/phantomjs/downloads npm install phantomjs
160 ##### Using PhantomJS from disk
162 If you plan to install phantomjs many times on a single machine, you can
163 install the `phantomjs` binary on PATH. The installer will automatically detect
164 and use that for non-global installs.
166 Cross-Platform Repositories
167 ---------------------------
169 PhantomJS needs to be compiled separately for each platform. This installer
170 finds a prebuilt binary for your operating system, and downloads it.
172 If you check your dependencies into git, and work on a cross-platform
173 team, then you need to tell NPM to rebuild any platform-specific dependencies. Run
179 as part of your build process. This problem is not specific to PhantomJS, and this
180 solution will work for any NodeJS package with native or platform-specific code.
182 If you know in advance that you want to install PhantomJS for a specific architecture,
183 you can set the environment variables: `PHANTOMJS_PLATFORM`
184 (to set target platform) and `PHANTOMJS_ARCH` (to set target
185 arch), where `platform` and `arch` are valid values for
186 [process.platform and process.arch](https://nodejs.org/api/process.html).
191 PhantomJS is not a library for NodeJS. It's a separate environment and code
192 written for node is unlikely to be compatible. In particular PhantomJS does
193 not expose a Common JS package loader.
195 This is an _NPM wrapper_ and can be used to conveniently make Phantom available.
196 It is not a Node JS wrapper.
198 I have had reasonable experiences writing standalone Phantom scripts which I
199 then drive from within a node program by spawning phantom in a child process.
201 Read the PhantomJS FAQ for more details: http://phantomjs.org/faq.html
205 An extra note on Linux usage, from the PhantomJS download page:
207 > There is no requirement to install Qt, WebKit, or any other libraries. It
208 > however still relies on Fontconfig (the package fontconfig or libfontconfig,
209 > depending on the distribution).
214 ##### Installation fails with `spawn ENOENT`
216 This is NPM's way of telling you that it was not able to start a process. It usually means:
218 - `node` is not on your PATH, or otherwise not correctly installed.
219 - `tar` is not on your PATH. This package expects `tar` on your PATH on Linux-based platforms.
220 - `bzip2` is not on your PATH.
222 Check your specific error message for more information.
224 ##### Installation fails with `Error: EPERM` or `operation not permitted` or `permission denied`
226 This error means that NPM was not able to install phantomjs to the file system. There are three
227 major reasons why this could happen:
229 - You don't have write access to the installation directory.
230 - The permissions in the NPM cache got messed up, and you need to run `npm cache clean` to fix them.
231 - You have over-zealous anti-virus software installed, and it's blocking file system writes.
233 ##### Installation fails with `Error: read ECONNRESET` or `Error: connect ETIMEDOUT`
235 This error means that something went wrong with your internet connection, and the installer
236 was not able to download the PhantomJS binary for your platform. Please try again.
238 ##### I tried again, but I get `ECONNRESET` or `ETIMEDOUT` consistently.
240 Do you live in China, or a country with an authoritarian government? We've seen problems where
241 the GFW or local ISP blocks github, preventing the installer from downloading the binary.
243 Try visiting [the download page](https://bitbucket.org/ariya/phantomjs/downloads) manually.
244 If that page is blocked, you can try using a different CDN with the `PHANTOMJS_CDNURL`
245 env variable described above.
247 ##### I am behind a corporate proxy that uses self-signed SSL certificates to intercept encrypted traffic.
249 You can tell NPM and the PhantomJS installer to skip validation of ssl keys with NPM's
250 [strict-ssl](https://www.npmjs.org/doc/misc/npm-config.html#strict-ssl) setting:
253 npm set strict-ssl false
256 WARNING: Turning off `strict-ssl` leaves you vulnerable to attackers reading
257 your encrypted traffic, so run this at your own risk!
259 ##### I tried everything, but my network is b0rked. What do I do?
261 If you install PhantomJS manually, and put it on PATH, the installer will try to
262 use the manually-installed binaries.
264 ##### I'm on Debian or Ubuntu, and the installer failed because it couldn't find `node`
266 Some Linux distros tried to rename `node` to `nodejs` due to a package
267 conflict. This is a non-portable change, and we do not try to support this. The
268 [official documentation](https://github.com/joyent/node/wiki/Installing-Node.js-via-package-manager#ubuntu-mint-elementary-os)
269 recommends that you run `apt-get install nodejs-legacy` to symlink `node` to `nodejs`
270 on those platforms, or many NodeJS programs won't work properly.
272 ##### I'm using an unsupported version of Linux or an ARM processor. I get errors about "Unexpected platform or architecture". What do I do?
274 We only have binaries available for common OS / processor configurations. Sorry.
276 You may be able to get a PhantomJS binary from your operating system's package
277 manager. Or you can build your own from source. If you put that binary on PATH,
278 this installer will use it (see "Deciding Where to Get PhantomJS" above).
284 Questions, comments, bug reports, and pull requests are all welcome. Submit them at
285 [the project on GitHub](https://github.com/Medium/phantomjs/). If you haven't contributed to an
286 [Medium](http://github.com/Medium/) project before please head over to the
287 [Open Source Project](https://github.com/Medium/open-source#note-to-external-contributors) and fill
288 out an OCLA (it should be pretty painless).
290 Bug reports that include steps-to-reproduce (including code) are the
291 best. Even better, make them in the form of pull requests.
296 [Dan Pupius](https://github.com/dpup)
297 ([personal website](http://pupius.co.uk)) and
298 [Nick Santos](https://github.com/nicks), supported by
299 [A Medium Corporation](http://medium.com/).
304 Copyright 2012 [A Medium Corporation](http://medium.com/).
306 Licensed under the Apache License, Version 2.0.
307 See the top-level file `LICENSE.txt` and
308 (http://www.apache.org/licenses/LICENSE-2.0).