PhantomJS 2.5 Beta

STATUS

The old installation problem is fixed. The original installer downloaded the binary from a Bitbucket URL that no longer exists (404); the package now installs from the platform binaries bundled in download/, with checksums verified on install. The toolchain has also been modernized (native Promises, current dependencies, node:test, ESLint flat config).

PhantomJS 2.5 itself is still unmaintained upstream and the binaries are final and unstable. For new work, prefer Playwright, Puppeteer, or Headless Chrome. See Platform Support below for what actually runs where — in particular, the binary is x86_64-only and does not run natively on Apple Silicon.

WHAT IS THIS?

An NPM wrapper for PhantomJS 2.5 Beta headless webkit with JS API.

Building and Installing

npm install phantomjs25-beta

The package installs the bundled Phantom binary for macOS (darwin, Intel), Ubuntu Linux (Xenial, x86_64) & Windows. The binaries are verified against known SHA-256 checksums during install.

Platform Support

PhantomJS 2.5 beta ships as an x86_64-only binary. What runs where:

| Platform | Installs | Runs | Notes | | --- | --- | --- | --- | | Linux x64 | ✅ | ✅ | Native. Needs a few base libs (see Docker below). | | Windows x64 | ✅ | ✅ | Native. | | macOS Intel (x64) | ✅ | ✅ | Installer applies an ad-hoc code signature. | | macOS Apple Silicon (arm64) | ⛔ | ⛔ | No arm64 build; the Intel binary is killed on launch even under Rosetta. See below. |

Apple Silicon (arm64) Macs

There is no arm64 PhantomJS build, and the Intel binary will not run on Apple Silicon (the OS rejects it with EBADARCH). To avoid installing something that cannot run, the installer fails fast on darwin/arm64 with guidance toward a maintained alternative (Playwright, Puppeteer, or Headless Chrome).

If you understand it will very likely not run and still want the binary placed (for example to repackage it elsewhere), opt in:

PHANTOMJS_ALLOW_ARM64=1 npm install phantomjs25-beta

To actually run PhantomJS 2.5 from an Apple Silicon Mac, use the x86_64 container below.

Running on x86_64 via Docker (works on Apple Silicon too)

The binary is linked against Ubuntu 16.04 (xenial) era libraries, so the provided Dockerfile builds a compatible x86_64 image. On Apple Silicon this runs under your container runtime's x86_64 emulation.

# Build (amd64 base images; emulated on Apple Silicon):
docker build -t phantomjs25-beta .

# Run:
docker run --rm phantomjs25-beta --version   # -> 2.5.0-development

# Run your own script:
docker run --rm -v "$PWD":/work -w /work phantomjs25-beta /work/your-script.js

Note: some Docker setups reject docker build --platform linux/amd64 with a "Multi-platform build is not supported for the docker driver" error. The platform is already pinned via the amd64 base images, so a plain docker build works; --platform linux/amd64 on docker run is fine.

Running

bin/phantomjs [phantom arguments]

And npm will install a link to the binary in node_modules/.bin.

Running via node

The package exports a path string that contains the path to the phantomjs binary/executable.

Below is an example of using this package via node.

var path = require('path')
var childProcess = require('child_process')
var phantomjs = require('phantomjs25-beta')
var binPath = phantomjs.path

var childArgs = [
  path.join(__dirname, 'phantomjs-script.js'),
  'some other argument (passed to phantomjs script)'
]

childProcess.execFile(binPath, childArgs, function(err, stdout, stderr) {
  // handle results
})

Versioning

The major and minor number tracks the version of PhantomJS that will be installed. The patch number is incremented when there is either an installer update or a patch build of the phantom binary.

Deciding Where To Get PhantomJS

By default the installer uses the binaries bundled in this repo's download/ directory, so installation works offline and does not depend on any external host (the original Bitbucket downloads are gone). The installer resolves the archive in this order:

1. An explicit download URL, if you set one (see below).
2. The bundled local archive for your platform in download/.
3. The remote mirror as a last resort. The archives are published on GitHub Releases (the original Bitbucket downloads no longer exist). Override the host with PHANTOMJS_CDNURL.

In every case the archive's SHA-256 checksum is verified before it is used.

Downloading from a custom URL

To fetch the binary from your own mirror instead of the bundled copy, pass a download URL:

npm install phantomjs25-beta --phantomjs_downloadurl=https://example.com/mirror/phantomjs-2.5.0-beta-macos.zip

or set the environment variable PHANTOMJS_DOWNLOADURL:

PHANTOMJS_DOWNLOADURL=https://example.com/mirror/phantomjs-2.5.0-beta-linux-ubuntu-xenial-x86_64.tar.gz npm install phantomjs25-beta

To only override the CDN host (keeping the standard file names), set PHANTOMJS_CDNURL.

Using PhantomJS from disk

If you plan to install phantomjs many times on a single machine, you can install the phantomjs binary on PATH. The installer will automatically detect and use that for non-global installs.

A Note on PhantomJS

PhantomJS is not a library for NodeJS. It's a separate environment and code written for node is unlikely to be compatible. In particular PhantomJS does not expose a Common JS package loader.

This is an NPM wrapper and can be used to conveniently make Phantom available It is not a Node JS wrapper.

I have had reasonable experiences writing standalone Phantom scripts which I then drive from within a node program by spawning phantom in a child process.

Read the PhantomJS FAQ for more details: http://phantomjs.org/faq.html

Linux Note

An extra note on Linux usage, from the PhantomJS download page:

This package is built on CentOS 5.8. It should run successfully on Lucid or more modern systems (including other distributions). There is no requirement to install Qt, WebKit, or any other libraries. It is however expected that some base libraries necessary for rendering (FreeType, Fontconfig) and the basic font files are available in the system.

Troubleshooting

Installation fails with spawn ENOENT

This is NPM's way of telling you that it was not able to start a process. It usually means:

• node is not on your PATH, or otherwise not correctly installed.
• tar is not on your PATH. This package expects tar on your PATH on Linux-based platforms.

Check your specific error message for more information.

Installation fails with Error: EPERM or operation not permitted or permission denied

This error means that NPM was not able to install phantomjs to the file system. There are three major reasons why this could happen:

• You don't have write access to the installation directory.
• The permissions in the NPM cache got messed up, and you need to run npm cache clean to fix them.
• You have over-zealous anti-virus software installed, and it's blocking file system writes.

Installation fails with Error: read ECONNRESET or Error: connect ETIMEDOUT

This error means that something went wrong with your internet connection, and the installer was not able to download the PhantomJS binary for your platform. Please try again.

I tried again, but I get ECONNRESET or ETIMEDOUT consistently.

Do you live in China, or a country with an authoritarian government? We've seen problems where the GFW or local ISP blocks bitbucket, preventing the installer from downloading the binary.

Try visiting the the download page manually. If that page is blocked, you can try using a different CDN with the PHANTOMJS_CDNURL env variable described above.

I am behind a corporate proxy that uses self-signed SSL certificates to intercept encrypted traffic.

You can tell NPM and the PhantomJS installer to skip validation of ssl keys with NPM's strict-ssl setting:

npm set strict-ssl false

WARNING: Turning off strict-ssl leaves you vulnerable to attackers reading your encrypted traffic, so run this at your own risk!

I tried everything, but my network is b0rked. What do I do?

If you install PhantomJS manually, and put it on PATH, the installer will try to use the manually-installed binaries.

I'm on Debian or Ubuntu, and the installer failed because it couldn't find node

Some Linux distros tried to rename node to nodejs due to a package conflict. This is a non-portable change, and we do not try to support this. The official documentation recommends that you run apt-get install nodejs-legacy to symlink node to nodejs on those platforms, or many NodeJS programs won't work properly.

Contributing

Questions, comments, bug reports, and pull requests are all welcome. Submit them at the project on GitHub.

PhantomJS 2.5 Beta archives sourced from Ariya's bitbucket repo.

Install.js HEAVILY lifted from Medium

Bug reports that include steps-to-reproduce (including code) are the best. Even better, make them in the form of pull requests.

Author

Darren Mackintosh.

License

Copyright 2017 Darren Mackintosh.

Licensed under the MIT License. See the top-level file LICENSE.txt.