Skip to content

Installing Qt and compiling capybara webkit

Mitchell Anicas edited this page Apr 4, 2016 · 103 revisions

capybara-webkit depends on a WebKit implementation from Qt, a cross-platform development toolkit. You'll need to download the Qt libraries to build and install the gem. You should install at least version 5.0, as the 4.8 series is now fairly old and contains a number of bugs that have since been fixed.

If you get an error when building, along the lines of fatal error: QObject: No such file or directory, you might be attempting the build against an older version of Qt. Make sure that the qmake in your PATH links to the latest version of Qt you have installed.

which qmake # to see where it links
rm `which qmake` # IF it is linking to an old version 

OS X El Capitan 10.11 and Yosemite 10.10


Qt 5.5 is the last version of Qt that capybara-webkit will support. The Qt project has dropped the WebKit bindings from binary releases in 5.6.

Install Qt 5.5 with homebrew:

brew tap homebrew/versions
brew install qt55

The Homebrew formula for qt5 is keg only which means binaries like qmake will not be symlinked into your /usr/local/bin directory and therefore will not be available for capybara-webkit.

To force Homebrew to symlink those binaries into your /usr/local/bin directory you can run:

brew link --force qt55

After running this command you should get the following output:

$ which qmake


Install qt5 with macports:

sudo port install qt5 # It's not qt5-mac anymore.

The default location for qt5's qmake is /opt/local/libexec/qt5/bin/qmake. If the qmake on path is different, you can indicate the correct one with QMAKE environment variable.

QMAKE=/opt/local/libexec/qt5/bin/qmake gem install capybara-webkit

OS X Mavericks 10.9 and Mountain Lion 10.8

Qt Official Distribution

Go to the QT website (general downloads site) and download the latest stable version of Qt.

Open the dmg files and install.

Note: if using the official packages and the Xcode compiler, ensure that the command line tools are installed as well. Otherwise compiling will result in precompiled header errors, and the QT_VERSION_CHECK macro will not be found.


Install Qt via homebrew. Grab latest Qt Formula (newer than this commit: Regular procedure is, first update the formulas, then try installing the built binary with:

brew update
brew install qt

If linking fails, ensure /usr/local/Frameworks exists and that you can write to it, and run brew link qt. If installation fails for some other reason, try building it from source (which can take more than an hour):

brew install qt --build-from-source

Mountain Lion and newer versions of OS X don't include X11, so it needs to be installed from

Video playback (mp4) on OSX requires Qt 5

capybara-webkit does work with mp4 videos on OSX 10.9 Mavericks, but not with Qt 4.8.6, only with Qt 5 (due to the updated Webkit implementation that ships with Qt 5). See this blog post, if interested in the details. Please note that some users have experienced hangs with Qt 5, while others have not. It might depend on your use case.

Qt 5 sadly requires the full Xcode to be installed (> 5 GB), as opposed to previous versions of Qt which didn't. NB: We warn against using tools that try to avoid installing the full Xcode by overwriting system files in /usr/bin, since that has caused problems for other users, forcing them to reinstall OSX.

When installing Qt 5, Qt 4.x should be uninstalled, to prevent interference. You can download the official Qt 5 dmg and install it that way, as previously explained. Once installed via the package, one simply needs to set the QMAKE environment variable and bundle. Or you can upgrade with Homebrew, in the following way:

brew uninstall qt
brew install qt5
ln -s /usr/local/Cellar/qt5/5.4.1/bin/qmake /usr/local/bin/qmake

The last line is to symlink qmake, so that qmake -v will run and report: QMake version 3.0 Using Qt version 5.4.1 in /usr/local/Cellar/qt5/5.4.1/lib. Your Qt 5 version might be more recent than 5.4.1. Also run brew doctor afterwards, to make sure everything is fine.

OS X Lion 10.7


Install Qt via homebrew. First update the formulas, then try installing the built binary with:

brew update
brew install qt

If that doesn't work, try building it from source (which can take more than an hour):

brew install qt --build-from-source


Install Qt via macports.

sudo port install qt5-mac

Debian testing, unstable, stable (wheezy), Ubuntu

sudo apt-get install qt5-default libqt5webkit5-dev gstreamer1.0-plugins-base gstreamer1.0-tools gstreamer1.0-x

QtWebKit now requires gstreamer; without gstreamer you may get EOFErrors on visit.

Ubuntu Trusty (14.04)

sudo apt-get install libqtwebkit-dev gstreamer1.0-plugins-base gstreamer1.0-tools gstreamer1.0-x

You should use qt4, using qt5 will fail with g++: internal compiler error: Segmentation fault (program cc1plus)


yum install qt-webkit-devel

Fedora 16

yum install qtwebkit-devel

If you are using a recent version of Fedora, the qmake executable is now called qmake-qt4. This will cause the gem installation to fail. So you need to add an environment variable your profile or the system profile.

export QMAKE=/usr/bin/qmake-qt4

Fedora 23

To install using qt5:

 [sudo] dnf install qt5-qtwebkit-devel
 export QMAKE=/usr/bin/qmake-qt5

Gentoo Linux

emerge dev-qt/qtwebkit

Arch Linux

pacman -S qt5-base qt5-webkit

openSUSE 11.4

sudo zypper in libqt4-devel libQtWebKit-devel

CentOS 7

yum install qtwebkit-devel # will work with the dash in between qt and webkit, but not if you are using chef
ln -s /usr/lib64/qt4/bin/qmake /usr/bin/qmake # or some other method to get qmake in your path like `export QMAKE`

You may need to install EPEL 7 ( to have qtwebkit-devel available.

CentOS 6.2

rpm -i 
yum install --enablerepo=atrpms-testing qt47-webkit-devel
export QMAKE=/usr/bin/qmake-qt47

CentOS 6.3

You cannot use qt47, it will conflict with the qt version that comes with 6.3. To be able to compile I had to add /usr/lib64/qt4/bin/ to my $PATH variable.

CentOS 6.3 + qt 4.8.5 + Ruby 2.0.0-p247 +capybara-webkit 1.0.0

You need qt 4.8.x at least with Ruby 2.0.x (Might be wrong, can't remember where I got it from).

After doing yum install [necessary_package], (qt48 is not available here so you have to compile.Word of caution: It takes around 6+ hours, please see this comment.)

tar xzvf qt-everywhere-opensource-src-4.8.5.tar.gz
cd qt-everywhere-opensource-src-4.8.5.tar.gz
./configure --embedded
gmake (caution:this will take a long time, if there's any error and you need to reconfigure, you can use 'gmake confclean')
gmake install

Qt 4.8.5 installed. Now gem install capybara-webkit should work. If it comes with Command 'qmake -spec linux-g++' not available that means capybara-webkit is looking for qmake at usr/bin/qmake, whereas the path of qmake is /usr/local/Trolltech/QtEmbedded-4.8.5/bin/qmake

Using $PATH, symlink or update alternative should help capybara-webkit to find qmake. This link shows how one can use update alternative.

CentOS 6.4

# Place this in a file in your /etc/yum.repos.d/ directory with a .repo extension

name=Software Collection for Qt 4.8

name=Software Collection for Qt 4.8 - Source
yum install qt48-qt-webkit-devel
ln -s /opt/rh/qt48/root/usr/include/QtCore/qconfig-64.h  /opt/rh/qt48/root/usr/include/QtCore/qconfig-x86_64.h
source /opt/rh/qt48/enable
export PATH=/opt/rh/qt48/root/usr/lib64/qt4/bin/${PATH:+:${PATH}}
gem install capybara-webkit -v "1.0.0"

CentOS 6.5/6.6

If having trouble when you try to bundle capybara - Need Qt 4.8.0+ to work with Ruby 2.x e.g.


Using xpath 2.0.0
Using capybara 2.4.1

Gem::Ext::BuildError: ERROR: Failed to build gem native extension.

    /home/username/.rvm/rubies/ruby-2.1.2/bin/ruby extconf.rb 
cd src/ && /usr/bin/qmake-qt4 /home/username/.rvm/gems/ruby-2.1.2/gems/capybara-webkit-1.1.0/src/ -spec /usr/lib/qt4/mkspecs/linux-g++ -unix -o Makefile.webkit_server
Project ERROR: At least Qt 4.8.0 is required to run capybara-webkit.
make: *** [sub-src-webkit_server-pro-qmake_all] Error 2
Command 'make qmake' failed


$ bundle install

stable.h:23:23: error: QWebElement: No such file or directory
stable.h:24:24: error: QWebSettings: No such file or directory
stable.h:34:20: error: QtWebKit: No such file or directory
make[1]: *** [build/webkit_server.gch/c++] Error 1
make[1]: Leaving directory `/home/vagrant/.rbenv/versions/2.1.0/lib/ruby/gems/2.1.0/gems/capybara-webkit-1.3.1/src'
make: *** [sub-src-webkit_server-pro-make_default-ordered] Error 2

make failed, exit code 2

Gem files will remain installed in /home/vagrant/.rbenv/versions/2.1.0/lib/ruby/gems/2.1.0/gems/capybara-webkit-1.3.1 for inspection.
Results logged to /home/vagrant/.rbenv/versions/2.1.0/lib/ruby/gems/2.1.0/extensions/x86_64-linux/2.1.0-static/capybara-webkit-1.3.1/gem_make.out
An error occurred while installing capybara-webkit (1.3.1), and Bundler cannot continue.
Make sure that `gem install capybara-webkit -v '1.3.1'` succeeds before bundling.


Build QT 4.8.x from source (as no packages available):

First, install dependencies of Qt if you don't install yet.

sudo yum install libxcb libxcb-devel xcb-util xcb-util-devel
sudo yum install flex bison gperf libicu-devel libxslt-devel ruby
sudo yum install libXrender-devel

Next, download a Qt source tarball.

cd ~/Downloads

Note: The version changes from time to time, so you may need to adjust like I had to change from 4.8.5 to 4.8.6.

tar xzvf qt-everywhere-opensource-src-4.8.6.tar.gz
cd qt-everywhere-opensource-src-4.8.6
./configure -opensource -nomake examples -nomake tests

Which edition of Qt do you want to use ?

Type 'c' if you want to use the Commercial Edition.
Type 'o' if you want to use the Open Source Edition.

Qt is now configured for building. Just run 'gmake'.
Once everything is built, you must run 'gmake install'.
Qt will be installed into /usr/local/Trolltech/Qt-4.8.6

To reconfigure, run 'gmake confclean' and 'configure'.

NOTE: Running gmake takes a bit, so be prepared. Go get some coffee :) Providing -j option makes your build faster. See man make for more details.

In CentOS 6.6, 'gmake' raise error for missing library gstreamer-app-0.10, so make sure run yum install 'pkgconfig(gstreamer-app-0.10)' to install it, before the long running gmake. (it takes me almost 2 hours)

sudo gmake

Then run:

sudo gmake install


sudo ln -s /usr/local/Trolltech/Qt-4.8.6/bin/qmake /usr/bin/qmake

CentOS 6.7

Instead of compiling source code, add the EPEL repository and qt5-webkit-devel by performing:

sudo yum install epel-release
sudo yum install qt5-qtwebkit-devel
QMAKE=/usr/lib64/qt5/bin/qmake gem install capybara-webkit

It's that easy! (If you want qmake to always work, add /usr/lib64/qt5/bin/ to your PATH variable)

CentOS 5.8 (and possibly below)

vim /etc/yum.repos.d/atrpms-testing.repo

Copy & paste the following into vim:

name=EL $releasever - $basearch - ATrpms

Save & close the file (:wq) and run the following:

rpm --import
yum --enablerepo=atrpms-testing install qt47-webkit-devel qt47-devel sqlite
vim /etc/profile.d/
export PATH=$PATH:/usr/lib/qt47/bin
export QMAKE=/usr/lib/qt47/bin/qmake-qt47

And finally, to install capybara-webkit (since for some reason remote install fails):

gem fetch capybara-webkit
gem install capybara-webkit.*.gem
rm capybara-webkit.*.gem

(If it comes with an error regarding "cannot find linux-g++" then it needs a symlink.):

ln -s /usr/lib64/qt47/bin/qmake /usr/lib/qt47/bin/qmake (might need to create those empty directory to fake it)
ln -s /usr/lib64/qt47/bin/qmake-qt47 /usr/lib/qt47/bin/qmake-qt47 (might need to create those empty directory to fake it)

then "gem install capybara-webkit" should work.


Install the webkit library port from /usr/ports/www/webkit-qt4.


You need a working Ruby installation that behaves well with a proper mingw32 compilation toolchain.

Download the latest Ruby version and DevKit from here, the compilation toolchain you need is Qt libraries v4.8.5 for Windows or higher, from here and MinGW from here. You'll also need a code editor or IDE (eg, Notepad++ , Sublimetext , Brackets).

Avoid installing in directory paths that have directory names with 'white space'. eg, C:\Ruby193 is good, whereas avoid C:\Program Files\Ruby193 because it has a 'whitespace' between Program and Files.

Step-by-step instructions.

1) Install Ruby and DevKit:

eg, C:\Ruby193 and C:\DevKit

2) Install Qt libraries v4.8.x for Windows ,

eg C:\Qt\4.8.5

It is essential that you install the Qt libraries with MinGW support, and not the ones who use nmake (provided by Visual Studio). In order to ensure that you've downloaded the correct version make sure mingw is part of the name of your downloaded binary.

You will also need to configure and build Qt, run this from the root of your Qt installation: configure.exe -platform win32-g++ -opensource -debug -debug-and-release -no-phonon -fast -nomake examples -nomake demos -no-dsp -no-vcproj -no-cetest -no-s60 -qt-sql-odbc -qt-sql-sqlite -plugin-sql-odbc -plugin-sql-sqlite -no-qt3support -no-opengl -no-openvg -no-incredibuild-xge and then mingw32-make

3) Run the DevKit installation scripts following the very clear directions for this step available here

4) Update some system paths, eg if you install Ruby, DevKit and Qt in the directories shown above:

  From ‘Start’, right click ‘Computer’, click ‘Advanced System Settings’, [if prompted, allow systemadvancedproperties.exe to run], click ‘Advanced’ tab, click ‘Environment variables…’ button, select ‘Path’ under user variables, click ‘edit’, and enter the following: C:\Ruby193\bin; c:\qt\4.8.5\bin;c:\devkit;c:\devkit\bin;C:\MinGW\msys\1.0\bin;C:\MinGW\bin

5) Perform the famous Frommel Workaround:

 Launch your favorite [code editor or IDE]( and do the following:

 a) open the qmake.conf of your platform (for me its C:\Qt\4.8.5\mkspecs\win32-g++)

 b) find the line beginning with QMAKE_IDC

 c) add the following line after the QMAKE_IDC line:

    QMAKE_LFLAGS = -static-libgcc -static-libstdc++

 d) save file and close editor

7) Open a command line in a window

 Start > Run > Open cmd

8) Clone latest version of capybara-webkit from Github:

 $ git clone git://

9) Bundle/Install capybara-webkit version:

 $ cd ruby193\capybara-webkit

 $ bundle install

10) Access the full Msys/MinGW environment:

 $ cd devkit

 $ devkitvars.bat

(Running devkitvars at this step is crucial, even though you may have run it previously at step 4 above.)

11) Compile the capybara-webkit within same cmd session as (10), run devkitvars again if you closed the cmd session before performing the following command:

 $ cd ruby193\capybara-webkit

 $ bundle exec rake build

12) Install the capybara-webkit gem:

 $ cd pkg && gem install capybara-webkit-1.0.0.gem

13) Smoke if you've got 'em

Discuss further on the capybara-webkit google group here

Something went wrong with that request. Please try again.