Appendix A: Building Qbs

Qbs can be installed from binary packages or built from sources, as described in this appendix. In addition, this appendix describes how to use Docker images for developing Qbs.

Supported Platforms

Qbs can be installed and run on the following platforms:

  • Windows 7, or later
  • Linux (tested on Debian 8 and 9, Ubuntu 16.04, OpenSuSE 13.2, and Arch Linux)
  • macOS 10.7, or later

System Requirements

To build Qbs from the source, you need:

  • Qt 5.9, or later
  • Windows: MinGW with GCC 4.9 or Microsoft Visual Studio 2015, or later
  • Linux: GCC 4.9, or later, or Clang 3.9.0, or later
  • macOS: Xcode 6.2, or later

An installed toolchain has to match the one that Qt was compiled with.


Building the Qbs documentation requires Python 2.7 or 3.2 or above, as well as some third party Python modules. These can be installed via pip:

pip install beautifulsoup4 lxml

Regenerating the man page requires the help2man tool.


To build Qbs, enter the following command:

qmake -r && make

Depending on your platform, you might use mingw32-make, nmake, or jom instead of make.

Installation by using make install is usually not needed. It is however possible, by entering the following command.


Configure Options

Qbs recognizes the following qmake CONFIG options to customize the build:

qbs_enable_unit_testsEnable additional autotests.
qbs_disable_rpathDisable the use of rpath. This can be used when packaging Qbs for distributions which do not permit the use of rpath, such as Fedora.
qbs_no_dev_installExclude header files from installation, that is, perform a non-developer build.
qbs_no_man_installExclude the man page from installation.
qbs_enable_project_file_updatesEnable API for updating project files. This implies a dependency to the Qt GUI module.
qbs_use_bundled_qtscriptUse the bundled QtScript library.

In addition, you can set the QBS_SYSTEM_SETTINGS_DIR environment variable before running qmake to specify a custom location for Qbs to look for its system-level settings.

Using Docker

A set of Docker images for developing Qbs (which are maintained by the Qbs team) is available on Docker Hub. Both Windows Server Core and Debian Linux container types are available.

Note: The source code for the Qbs development Docker images is located in the docker/ directory of the Qbs source tree, if you wish to build them yourself.

Linux Containers

The easiest way to get started is to build Qbs using a Linux container. These types of containers are supported out of the box on all the supported host platforms: Windows, macOS, and Linux. Run the following to download the Qbs development image based on Debian 9 Stretch:

docker pull qbsbuild/qbsdev:stretch

You can then create a new container with the Qbs source directory mounted from your host machine's file system, by running:

docker run -it -v $PWD:/qbs -w /qbs qbsbuild/qbsdev:stretch

Or with a slightly different syntax for Windows:

docker run -it -v %CD%:/qbs -w /qbs qbsbuild/qbsdev:stretch

You will now be in an interactive Linux shell where you can develop and build Qbs.

Windows Containers

To build Qbs for Windows using Windows containers, your host OS must be running Windows 10 Pro and have Hyper-V enabled. Switch your Docker environment to use Windows containers, then run the following command to download the Windows 10 Qbs development image:

docker pull qbsbuild/qbsdev:windowsservercore

You can then create a new container with the Qbs source directory mounted from your host machine's file system, by running:

docker run -it -v %CD%:C:\qbs -w C:\qbs qbsbuild/qbsdev:windowsservercore

If you want to use Windows containers on a macOS or Linux host, you will have to create a virtual machine running Windows 10 and register it with docker-machine. There is at least one Open Source project that helps to facilitate this by using using Packer, Vagrant, and VirtualBox.

The docker run command to spawn a Windows container on a Unix host will look slightly different (assuming windows is the name of the Docker machine associated with the Windows container hosting VM):

eval $(docker-machine env windows)
docker run -it -v C:$PWD:C:\\qbs -w C:\\qbs qbsbuild/qbsdev:windowsservercore

Building Release Packages

Release packages for Qbs for Windows can be built using the following command on Windows:

docker run --rm -v %CD%:C:\qbs -w C:\qbs qbsbuild/qbsdev:windowsservercore cmd /c scripts\make-release-archives

For building release packages for Windows on macOS or Linux:

eval $(docker-machine env windows)
docker run --rm -v C:$PWD:C:\\qbs -w C:\\qbs qbsbuild/qbsdev:windowsservercore cmd /c scripts\\make-release-archives

© 2018 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.