Specifying Build Settings

Different build configurations allow you to quickly switch between different build settings. By default, Qt Creator creates debug, release, and profile build configurations. A debug build contains additional debug symbols that you need for debugging the application but that you can leave out from the release version. Generally, you use the debug configuration for testing and the release configuration for creating the final installation file. A profile configuration is an optimized release build that is delivered with separate debug information. It is best suited for analyzing applications.

You specify build settings in the Projects mode. To add a new build configuration, click Add and select the type of configuration you would like to add. You can add as many build configurations as you need.

To delete the build configuration currently selected, click Remove.

Editing Build Configurations

Select the build configuration to edit in the Edit build configuration field.

By default, Qt Creator builds projects in a separate directory from the source directory, as shadow builds. This keeps the files generated for each build and run kit separate. If you only build and run with a single kit, you can deselect the Shadow build checkbox.

To make in-source builds the default option for all projects, select Tools > Options > Build & Run > General, and enter a period (.) in the Default build directory field.

Starting External Processes

Qt Creator executes external processes to accomplish tasks such as building and running applications. To execute the processes, Qt Creator uses shell commands that are native to the system. It constructs the commands from an executable name and optional command line arguments.

The executable name is specified in the executable fields: qmake, Make, Command, or Executable. It is either derived from the project or specified manually. When you specify executables manually, you can reference environment variables and Qt Creator variables. However, no quoting rules apply.

You can specify command-line arguments in the arguments fields: Additional arguments, Command arguments, Make arguments, Arguments, Default Arguments, or Extra arguments. You can create shell command lines that can contain redirection and other advanced constructs. However, some more complex use cases, such as piping test data into the application being tested or grouping commands, are not supported because the value of the Executable field is always placed first when constructing the command.

Using Environment Variables

You can use any environment variables as values in the fields. For a list of variable names, click Build Environment > Details in the Build Settings. Environment variables are referenced using the native syntax: $VARNAME or ${VARNAME} on Unix and %VARNAME% on Windows.

Using Qt Creator Variables

You can use Qt Creator variables in arguments, executable paths, and working directories. The variables take care of quoting their expansions, so you do not need to put them in quotes. Select the (Variables) button in a field to select from a list of variables that are available in a particular context.

The following syntax enables you to use environment variables as Qt Creator variables: %{Env:VARNAME}.

Qt Creator uses pattern substitution when expanding variable names. To replace the first match of pattern within variable with replacement, use:


To replace all matches of pattern within variable with replacement, use:


The pattern can be a regular expression and the replacement can contain backreferences. For example, if %{variable} is my123var, then %{variable/(..)(\d+)/\2\1} is expanded to 123myvar.

To use the default value if the variable is not set, use:


Build Steps

The build system of Qt Creator is built on qmake and make. In Build Steps you can change the settings for qmake and make. Qt Creator runs the make command using the Qt version defined for the current build configuration.

"Build steps"

To override the shell command that Qt Creator constructs by default, disable or remove the build step and add a custom build step that specifies another shell command.

To generate debug symbols also for applications compiled in release mode, select the Generate separate debug info check box. For more information, see Using the CPU Usage Analyzer.

Qt Creator is integrated to Qt Quick Compiler (commercial only) that enables you to compile QML source code into the final binary. This improves the startup time of the application and eliminates the need to deploy QML files together with the application. Qt Creator new project wizards create projects that the Qt Quick Compiler can compile, because they are set up to use the Qt Resource System. To compile Qt Quick projects, select the Enable Qt Quick Compiler check box.

Note: For more information about the build steps when using Qbs, see Building Applications with Qbs.

Adding Custom Build Steps

To add custom steps to the build settings, select Add Build Step > Custom Process Step.

By default, custom steps are enabled. To disable a custom step, select the (Disable) button.

"Custom Process Step"

Executing Custom Commands

To execute custom commands when building for embedded devices, select Add Build Step > Custom Remote Command (via adb shell) (commercial only) and enter the command to execute.

Clean Steps

You can use the cleaning process to remove intermediate files. This process might help you to fix obscure issues during the process of building a project.

"Clean steps"

You can define the cleaning steps for your builds in the Clean Steps:

  • To add a clean step using make or a custom process, click Add Clean Step and select the type of step you want to add.

    By default, custom steps are enabled. To disable a custom step, select the Disable button.

  • To remove a clean step, click Remove Item.
  • To change the order of steps, click (Move Up) and (Move Down).

Note: For more information about the cleaning steps when using Qbs, see Building Applications with Qbs.

Build Environment

You can specify the environment you want to use for building in the Build Environment section. By default, the environment in which Qt Creator was started is used and modified to include the Qt version. Depending on the selected Qt version, Qt Creator automatically sets the necessary environment variables. You can edit existing environment variables or add, reset and unset new variables based on your project requirements.

"Build Environment"

Note: The changes are stored in the local project specific .pro.user file. Therefore, they are not suitable for sharing between developers or development PCs. To share settings, incorporate them into the build system. For example, if you use qmake, make the changes in the .pro file.

Batch Editing

To modify environment variable values for build or run environments, select Batch Edit in the build or run settings and enter environment variables in the Edit Environment dialog.

To remove a variable value from the environment, enter the variable name. For example, TEST sets the value of the TEST variable empty when building or running the project.

To add a variable value to the environment, enter the variable name and value, separated by the equals sign. For example, the following line prepends /opt/bin to the existing PATH:


To add or remove several variables, place them on separate lines. The order is important. If you remove a value on a line, you cannot refer to it on the following lines. However, you can remove a value after you have referred to it on an earlier line.

Clearing the System Environment

To build with a clean system environment, select the Clear system environment check box. Qt Creator discards the current environment, and populates a clean system environment with the environment variables that the compilers and tools need. Therefore, the environment is never totally empty, even after you clear it.

© 2016 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.