.

Tags:

This blog post describes various ways to install PhantomJS, the scriptable headless WebKit, on Mac OS X system (Snow Leopard and Lion), sorted from the most recommended way to the least recommended way.

While the documentation wiki contains a clear explanation on how to start using PhantomJS on Mac OS X, I understand temptation to skip reading something and start doing real stuff. This post thus serves as another safety net for such cases. It also helps to clarify some misunderstanding.

Note that these instructions apply to PhantomJS 1.4 (Glory of the Snow). Future versions may or may not require different steps.

Install the binary package

This is the fastest and easiest way. Go to the download page, find the ZIP file for Mac OS X, then download it. The size is usually around 9 MB so it should be pretty fast. Once it is downloaded, unzip the file (e.g. click on Finder) and that’s it!

It’s recommended to store the executable somewhere in your PATH. Also, the special file Info.plist is needed to avoid the Dock icon from flashing.

Note that the ZIP package is self-contained. You do not need to install Qt beforehand. I repeat: there is no need to install or prepare anything. In other words, the steps mentioned above would work on a fresh (clean) install of Mac OS X.

Always stick to this binary package approach unless there is a strong reason not to do so. It saves you a lot of time.

Compile statically

Building everything manually takes time and effort. Fortunately a convenient build script is included. From the download page, find the source tarball, get it and then extract it. After that:

cd deploy && ./build-mac.sh

What does the script do? It will download Qt 4.8 source code from Nokia web site, extract the tarball, apply some patches, run configure, build Qt statically, and then finally build PhantomJS.

As with the previous approach, the build script has zero dependency. You do not need to compile Qt manually. In fact, run the build script on any Mac OS X system and it should work (of course, you need to have Xcode installed for the compilers, SDK, etc). The download might take a while (since Qt tarball is huge, around 230 MB), thus make sure you are not on a slow Internet connection.

Some patches are applied because of the urgent need, e.g. to prevent QUrl crash, to avoid library confusion, or to allow file upload. There are also others important requirements, see the release notes for details.

The entire build is carried out with 4 (four) simultaneous compile jobs under the assumption that everyone uses a Mac machine with at least hyperthreaded dual-core CPU. On a typical modern machine, the build step lasts for about 30 minutes. Fast hard drive is recommended, but it is not mandatory.

If UPX is detected on the system, the final executable will be compressed. This should significantly reduce the size from 26 MB to just about 10 MB.

Once you are finished with these steps, what you have is a statically built PhantomJS with no external dependency (you should be able to copy it to another machine if needed). In fact, this is exactly what you got as if you follow the first approach (using the binary package).

Use MacPorts or Homebrew

This approach only makes sense if you already have Qt installed, possibly because it is needed by some other applications. Otherwise, running

port install phantomjs

or

brew install phantomjs

will potentially keep your machine busy for hours because it will build the entire Qt library first. With Homebrew, it’s not so bad because Bottle likely save the time.

While the end result might look the same, there are two important differences compared to the second approach. First, the convenient static build script build-mac.sh only compiles the necessary parts of Qt needed for PhantomJS. For example, it skips building the examples, demos, tools, etc. This cuts the overall time. Second, since MacPorts and Homebrew builds the vanilla Qt, some problems which are solved by patching (see the second approach) might arise.

Keep the above differences into account to avoid future headache.

Update: PhantomJS Homebrew formula has been updated so it will install the same exact binary like in the first two approaches. If you already have Homebrew, this is easy and fast, so go ahead and brew install phantomjs and enjoy!

  • n1k0

    Just a quick note about brew bottles, they’re only available for OSX Lion.

    • ariya

      Thanks for the additional info!

    • http://ariya.ofilabs.com/ Ariya Hidayat

      Thanks for the additional info!

  • n1k0

    Just a quick note about brew bottles, they’re only available for OSX Lion.

    • ariya

      Thanks for the additional info!

    • http://ariya.ofilabs.com/ Ariya Hidayat

      Thanks for the additional info!

  • http://operation-reset.com/ Vincent Carré

    Hi Ariya.
    I installed the binary package of PhantomJS on Mac OS X. I put the executable on my PATH, but where should I put the Info.plist file?
    (On developer.apple.com it says the Info.plist file normally resides in the bundle’s Contents directory, but in this case, there is no bundle.)

    • http://ariya.ofilabs.com/ Ariya Hidayat

      Just like in the ZIP file, place the Info.plist file in the same directory as the executable.

      • http://operation-reset.com/ Vincent Carré

        Great, thanks!

  • http://operation-reset.com/ Vincent Carré

    Hi Ariya.
    I installed the binary package of PhantomJS on Mac OS X. I put the executable on my PATH, but where should I put the Info.plist file?
    (On developer.apple.com it says the Info.plist file normally resides in the bundle’s Contents directory, but in this case, there is no bundle.)

    • http://ariya.ofilabs.com/ Ariya Hidayat

      Just like in the ZIP file, place the Info.plist file in the same directory as the executable.

      • http://operation-reset.com/ Vincent Carré

        Great, thanks!

  • Finalfire

    Is there some workaround for using PhantomJS on Leopard?

    • http://ariya.ofilabs.com/ Ariya Hidayat

      Unfortunately, without a Leopard machine it’s hard for me to debug the issue.

      • Finalfire

        I resolved compiling qt etc. I’m trying to debug the issue about Leopard.

        • http://ariya.ofilabs.com/ Ariya Hidayat

          Maybe Qt configure script must be run with ‘sdk /Developer/SDKs/MacOSX10.5sdk’ option. If you send me an email, I can provide a rebuilt binary for you to test.

  • Finalfire

    Is there some workaround for using PhantomJS on Leopard?

    • http://ariya.ofilabs.com/ Ariya Hidayat

      Unfortunately, without a Leopard machine it’s hard for me to debug the issue.

      • Finalfire

        I resolved compiling qt etc. I’m trying to debug the issue about Leopard.

        • http://ariya.ofilabs.com/ Ariya Hidayat

          Maybe Qt configure script must be run with ‘sdk /Developer/SDKs/MacOSX10.5sdk’ option. If you send me an email, I can provide a rebuilt binary for you to test.

  • Fabio Miranda Costa

    Hi Aryia, I’ve created a homebrew formula with the correct way of installing phantomjs on macosx, if you could verify that eveything is ok so we can have a nice and fast `brew install phantomjs` in the near future, it would be awesome! https://github.com/mxcl/homebrew/pull/11225

  • Pingback: Css3-Verläufe als Grafik exportieren | Frontend Log()

  • Hugo

    Hi:

    I’m extracting the zip file in the downloads folder of my mac as explained and nothing happens, it doesn’t work…I’m back to this after lots of trying to install the executable in my path…Can you help me out with this?

    Thanks!!