Skip to content

Getting Started with Source and Builds

本主题说明如何获取QGroundControl源代码并在本机或在Vagrant(虚拟机)环境中构建它。 本主题还提供其他可选功能信息及特定于操作系统的功能信息。 It also provides information about optional or OS specific functionality.


If you just want to test (and not debug) a recent build of QGroundControl you can use the Daily Build. Versions are provided for all platforms.


QGroundControl 的源代码保存在 github 上,下载地址为:。 QGroundControl源代码在Apache 2.0和GPLv3下是双许可的。 有关更多信息,请参阅:许可证。 It is dual-licensed under Apache 2.0 and GPLv3.

要获取源文件, 请执行以下操作:

  1. Clone the repo (or your fork) including submodules:

    克隆存储库 (或您的分叉), 包括子模块: `git clone --recursive -j8`
  2. Update submodules (required each time you pull new source code):

    2.更新子模块(每次拉新源代码时都这样做): `git submodule update --recursive`


提示:不能使用Github以zip形式下载源文件,因为zip压缩包中不包含相应的子模块源代码。 你必须使用git工具! You must use git!


Using Containers

We support Linux builds using a container found on the source tree of the repository, which can help you develop and deploy the QGC apps without having to install any of the requirements on your local environment.

Container Guide

Native Builds

QGroundControl builds are supported for macOS, Linux, Windows, and Android. Creating a version of QGC for iOS is theoretically possible but is no longer supported as a standard build. QGroundControl uses Qt as its cross-platform support library.

The required version of Qt is 6.6.1 (only).


Do not use any other version of Qt! QGC has been thoroughly tested with the specified version of Qt (6.6.1). There is a significant risk that other Qt versions will inject bugs that affect stability and safety (even if QGC compiles).

For more information see: Qt 6 supported platform list.


Native CentOS Builds are also supported, but are documented separately (as the tested environment is different).


You must install Qt as described below instead of using pre-built packages from say, a Linux distribution.

To install Qt:

  1. 下载并运行Qt Online Installer

    • Ubuntu:
      • 使用以下命令将下载的文件设置为可执行文件:chmod + x
      • You may also need to install libxcb-cursor.
  2. In the installer Select Components dialog choose: Qt 6.6.1.

    Then install the following components:

    • Under _Qt 6.6.1 select:
      • Depending on the OS you want to build for:
        • Windows: MSVC 2019 64 bit
        • MacOS: macOS
        • Linux: Desktop gcc 64-bit
        • Android: Android
      • Qt 5 Compatibility Module
      • Qt Shader Tools
    • Under Additional Libraries select:
      • Qt Charts
      • Qt Connectivity
      • Qt Location (TP)
      • Qt Multimedia
      • Qt Positioning
      • Qt Serial Port
      • Qt Speech
  3. Install Additional Packages (Platform Specific)

    • Ubuntu: sudo apt-get install speech-dispatcher libudev-dev libsdl2-dev patchelf build-essential
    • Fedora: sudo dnf install speech-dispatcher SDL2-devel SDL2 systemd-devel patchelf
    • Arch Linux: pacman -Sy speech-dispatcher patchelf
    • OSX Setup
    • Android Setup
  4. Install Optional/OS-Specific Functionality

    Optional features that are dependent on the operating system and user-installed libraries are linked/described below. These features can be forcibly enabled/disabled by specifying additional values to qmake. :::

Building using Qt Creator

  1. Launch Qt Creator and open the project.

  2. In the Projects section, select the appropriate kit for your needs:

    • OSX: Desktop Qt 6.6.1 clang 64 bit


      iOS builds must be built using XCode.

    • Ubuntu: Desktop Qt 6.6.1 GCC 64bit

    • Windows: Desktop Qt 6.6.1 MSVC2019 64bit

    • Android: Android for armeabi-v7a (GCC 4.9, Qt 6.6.1)

      • JDK11 is required. You can confirm it is being used by reviewing the project setting: Projects > Manage Kits > Devices > Android (tab) > Android Settings > JDK location.
  3. Build using the "hammer" (or "play") icons:

    QtCreator Build Button

Install Visual Studio 2019 (Windows Only)

The Windows compiler can be found here: Visual Studio 2019 compiler (64 bit)

When installing, select Desktop development with C++ as shown:

Visual Studio 2019 - Select Desktop Environment with C++


Visual Studio is ONLY used to get the compiler. Actually building QGroundControl should be done using Qt Creator or qmake as outlined below.

Build using qmake on CLI

Example commands to build a default QGC and run it afterwards:

  1. Make sure you cloned the repository and updated the submodules before, see chapter Source Code above and switch into the repository folder: cd qgroundcontrol

    cd qgroundcontrol
  2. Create and enter a shadow build directory:

    mkdir build
    cd build
  3. Configure the build using the qmake script in the root of the repository: qmake ../

  4. Run make to compile and link. To accelerate the process things you can use the -j{number of threads} parameter.

    `make -j12`


    You can also specify build time flags here. For example, you could disable airmap inclusion using the command:

  5. Run the QGroundcontrol binary that was just built: ./staging/QGroundControl



Vagrant can be used to build and run QGroundControl within a Linux virtual machine (the build can also be run on the host machine if it is compatible).

  1. Download and Install Vagrant
  2. From the root directory of the QGroundControl repository run vagrant up
  3. To use the graphical environment run vagrant reload

Additional Build Notes for all Supported OS

  • Parallel builds: For non Windows builds, you can use the -j# option to run parellel builds.
  • If you get this error when running QGroundControl: /usr/lib/x86_64-linux-gnu/ version 'GLIBCXX_3.4.20' not found., you need to either update to the latest gcc, or install the latest libstdc++.6 using: sudo apt-get install libstdc++6.
  • Unit tests: To run the unit tests, build in debug mode with UNITTEST_BUILD definition, and then copy deploy/ script into the debug directory before running the tests.

Building QGC Installation Files

You can additionally create installation file(s) for QGroundControl as part of the normal build process.


On Windows you will need to first install NSIS.

To add support for installation file creation you need to add CONFIG+=installer to your project file, or when you call qmake.

To do this in Qt Creator:

  • Open Projects > Build > Build Steps > qmake > Additional arguments.
  • Enter CONFIG+=installer as shown: Installer