Qt Reference Documentation

# Using qt.conf

The `qt.conf` file overrides the hard-coded paths that are compiled into the Qt library. These paths are accessible using the QLibraryInfo class. Without `qt.conf`, the functions in QLibraryInfo return these hard-coded paths; otherwise they return the paths as specified in `qt.conf`.

Without `qt.conf`, the Qt libraries will use the hard-coded paths to look for plugins, translations, and so on. These paths may not exist on the target system, or they may not be accesssible. Because of this, you need `qt.conf` to make the Qt libraries look elsewhere.

QLibraryInfo will load `qt.conf` from one of the following locations:

1. `:/qt/etc/qt.conf` using the resource system
2. on Mac OS X, in the Resource directory inside the application bundle, for example `assistant.app/Contents/Resources/qt.conf`
3. in the directory containing the application executable, i.e. QCoreApplication::applicationDirPath() + QDir::separator() + "qt.conf"

The `qt.conf` file is an INI text file, as described in the QSettings documentation. The file should have a `Paths` group which contains the entries that correspond to each value of the QLibraryInfo::LibraryLocation enum. See the QLibraryInfo documentation for details on the meaning of the various locations.

Entry | Default Value
--- | ---
Prefix | QCoreApplication::applicationDirPath()
Documentation | `doc`
Headers | `include`
Libraries | `lib`
Binaries | `bin`
Plugins | `plugins`
Imports | `imports`
Data | `.`
Translations | `translations`
Settings | `.`
Examples | `.`
Demos | `.`

Absolute paths are used as specified in the `qt.conf` file. All paths are relative to the `Prefix`. On Windows and X11, the `Prefix` is relative to the directory containing the application executable (QCoreApplication::applicationDirPath()). On Mac OS X, the `Prefix` is relative to the `Contents` in the application bundle. For example, `application.app/Contents/plugins/` is the default location for loading Qt plugins. Note that the plugins need to be placed in specific sub-directories under the `plugins` directory (see How to Create Qt Plugins for details).

For example, a `qt.conf` file could contain the following:

     [Paths]
     Prefix = /some/path
     Translations = i18n

Subgroups of the `Paths` group may be used to specify locations for specific versions of the Qt libraries. Such subgroups are of the form `Paths/x.y.z`, where x is the major version of the Qt libraries, y the minor, and z the patch level. The subgroup that most closely matches the current Qt version is used. If no subgroup matches, the `Paths` group is used as the fallback. The minor and patch level values may be omitted, in which case they default to zero.

For example, given the following groups:

     Paths
     Paths/4
     Paths/4.1
     Paths/4.2.5
     Paths/6

The current version will be matched as shown:

- 4.0.1 matches `Paths/4`
- 4.1.5 matches `Paths/4.1`
- 4.6.3 matches `Paths/4.2.5` (because 4.2.5 is the latest version with the same major version number)
- 5.0.0 matches `Paths`
- 6.0.2 matches `Paths/6`