Installing Qt and compiling capybara webkit

Vladimir Moravec edited this page Jul 27, 2016 · 111 revisions

Instructions for Editing This Page

If you don't see your system here and you get capybara-webkit to compile using Qt 5, please edit this page to share your knowledge with future users.

Please do not edit this page to recommend Qt 4!

Qt 4 is several years old and contains a version of WebKit with many serious defects. Support for Qt 4 will be dropped in any future feature releases and is not supported by the capybara-webkit team. If you add instructions to this page, please make sure your instructions build using Qt 5.

Thanks for contributing!

Instructions for Installing

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, Jessie), gitlab-ci, 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 libqt4-dev libqtwebkit-dev


yum install qt-webkit-devel

Fedora 16

If you know how to compile using Qt 5 under Fedora 16, please edit this page and add instructions.

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 13.2, openSUSE Leap 42.1

zypper install libqt4-devel libQtWebKit-devel

CentOS 7

If you know how to compile using Qt 5 under CentOS 7, please edit this page and add instructions.

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)

If you know how to compile using Qt 5 under CentOS 5.8, please edit this page and add instructions.


If you know how to compile using Qt 5 under FreeBSD, please edit this page and add instructions.


If you know how to compile using Qt 5 under Windows, please edit this page and add instructions.