QStandardPaths Class
The QStandardPaths class provides methods for accessing standard paths. More...
| Header: | #include <QStandardPaths> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Core)target_link_libraries(mytarget PRIVATE Qt6::Core) |
| qmake: | QT += core |
Public Types
| enum | LocateOption { LocateFile, LocateDirectory } |
| flags | LocateOptions |
| enum | StandardLocation { DesktopLocation, DocumentsLocation, FontsLocation, ApplicationsLocation, MusicLocation, …, GenericStateLocation } |
Static Public Members
| QString | displayName(QStandardPaths::StandardLocation type) |
| QString | findExecutable(const QString &executableName, const QStringList &paths = QStringList()) |
| QString | locate(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile) |
| QStringList | locateAll(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile) |
| void | setTestModeEnabled(bool testMode) |
| QStringList | standardLocations(QStandardPaths::StandardLocation type) |
| QString | writableLocation(QStandardPaths::StandardLocation type) |
Detailed Description
This class contains functions to query standard locations on the local filesystem, for common tasks such as user-specific directories or system-wide configuration directories.
Member Type Documentation
enum QStandardPaths::LocateOption
flags QStandardPaths::LocateOptions
This enum describes the different flags that can be used for controlling the behavior of QStandardPaths::locate and QStandardPaths::locateAll.
| Constant | Value | Description |
|---|---|---|
QStandardPaths::LocateFile | 0x0 | return only files |
QStandardPaths::LocateDirectory | 0x1 | return only directories |
The LocateOptions type is a typedef for QFlags<LocateOption>. It stores an OR combination of LocateOption values.
enum QStandardPaths::StandardLocation
This enum describes the different locations that can be queried using methods such as QStandardPaths::writableLocation, QStandardPaths::standardLocations, and QStandardPaths::displayName.
QStandardPaths describes each location along two independent axes: app scope (private to the calling application or shared between applications) and user scope (rooted in the calling user's directories or system-wide). Each enum value below indicates its app scope; the platform tables further down show its user scope.
Data interchange with other users is out of the scope of QStandardPaths.
App scope
A location is either application-specific (private to the calling application) or generic (shared between applications run by the same user). Application-specific locations should be assumed to be unreachable by other applications, even when run by the same user.
Sandboxed applications
For sandboxed applications, on platforms such as iOS, Android, or macOS, even generic locations can be rooted in the application's sandbox container (<APPROOT> in the tables below). In practice this collapses the app-scope distinction, with every location becoming effectively application-specific, and the user's system-wide shared directories reachable only through system-provided pickers, for example, QFileDialog.
User scope
A location is either user-local (rooted in the calling user's home or per-user directories) or system-wide (populated by the OS or by package managers, shared across users, and usually read-only to applications).
Querying writableLocation() returns the directory where files should be written, which is typically user-scoped. For application-specific locations it is also scoped to the calling application.
Querying standardLocations() returns the writable path first (if it can be determined), followed by zero or more additional locations, including both user-local and system-wide fallbacks. The additional locations are used by locate() and locateAll() to find existing files.
Sandboxed applications
For sandboxed applications, system-wide locations typically fall outside the application's sandbox container, and may not exist from the application's point of view, let alone be readable or writable. They are still listed in the platform tables below for symmetry with the non-sandboxed case, and to cover applications that have been granted access through entitlements or user-driven pickers. Callers should not assume that every entry returned by standardLocations() exists or is accessible.
| Constant | Value | Description |
|---|---|---|
QStandardPaths::DesktopLocation | 0 | The user's desktop directory. On systems with no concept of a desktop, this is the same as HomeLocation. Generic. |
QStandardPaths::DocumentsLocation | 1 | Directory containing document files. The returned path is never empty. Generic. |
QStandardPaths::FontsLocation | 2 | Directory containing fonts. Note that installing fonts may require additional, platform-specific operations. Generic. |
QStandardPaths::ApplicationsLocation | 3 | Directory containing applications (either executables, application bundles, or shortcuts to them). Note that installing applications may require additional, platform-specific operations. Files, folders, or shortcuts in this directory are platform-specific. Generic. |
QStandardPaths::MusicLocation | 4 | Directory containing music or other audio files. If no such directory exists, a sensible fallback for storing documents is returned. Generic. |
QStandardPaths::MoviesLocation | 5 | Directory containing movies and videos. If no such directory exists, a sensible fallback for storing documents is returned. Generic. |
QStandardPaths::PicturesLocation | 6 | Directory containing pictures or photos. If no such directory exists, a sensible fallback for storing documents is returned. Generic. |
QStandardPaths::TempLocation | 7 | Directory where temporary files can be stored. The returned value might be application-specific, shared among other applications for this user, or even system-wide. The returned path is never empty. Varies. |
QStandardPaths::HomeLocation | 8 | The user's home directory (the same as QDir::homePath()). On Unix systems, this is equal to the HOME environment variable. The returned path is never empty. Generic. |
QStandardPaths::AppLocalDataLocation | 9 | The local data path on Windows. On all other platforms, the same as AppDataLocation. Application-specific. This enum value was added in Qt 5.4. |
QStandardPaths::CacheLocation | 10 | Directory where non-essential (cached) data should be written. The returned path is never empty. Application-specific. |
QStandardPaths::GenericCacheLocation | 15 | Directory where non-essential (cached) data shared across applications should be written. Note that the returned path may be empty if the system has no concept of shared cache. Generic. |
QStandardPaths::GenericDataLocation | 11 | Directory where persistent data shared across applications can be stored. The returned path is never empty. Generic. |
QStandardPaths::RuntimeLocation | 12 | Directory where runtime communication files should be written, like Unix local sockets. The returned path may be empty on some systems. Generic. |
QStandardPaths::ConfigLocation | 13 | Directory where configuration files should be written. The returned path is never empty. May be generic or application-specific (see AppConfigLocation and GenericConfigLocation for explicit variants). Varies. |
QStandardPaths::DownloadLocation | 14 | Directory for downloaded files. If no such directory exists, a sensible fallback for storing documents is returned. Generic. |
QStandardPaths::GenericConfigLocation | 16 | Directory where configuration files shared between multiple applications should be written. The returned path is never empty. Generic. |
QStandardPaths::AppDataLocation | 17 | Directory where persistent application data can be stored. To obtain a path to store data to be shared with other applications, use GenericDataLocation. The returned path is never empty. On Windows, this returns the roaming path. Application-specific. This enum value was added in Qt 5.4. |
QStandardPaths::AppConfigLocation | 18 | Directory where configuration files should be written. The returned path is never empty. Application-specific. This enum value was added in Qt 5.5. |
QStandardPaths::PublicShareLocation | 19 | Directory where publicly shared files and directories can be stored. Note that the returned path may be empty if the system has no concept of a publicly shared location. Generic. This enum value was added in Qt 6.4. |
QStandardPaths::TemplatesLocation | 20 | Directory where template files can be stored. Note that the returned path may be empty if the system has no concept of a templates location. Generic. This enum value was added in Qt 6.4. |
QStandardPaths::StateLocation (since Qt 6.7) | 21 | Directory where application state data files should be written. The returned path is never empty. Application-specific. |
QStandardPaths::GenericStateLocation (since Qt 6.7) | 22 | Directory where shared state data files across applications should be written. The returned path is never empty. Generic. |
The following table gives examples of paths on different operating systems. The first path is the writable path (unless noted). Other, additional paths, if any, represent non-writable locations.
| Path type | macOS | Windows |
|---|---|---|
| DesktopLocation | "~/Desktop" | "C:/Users/<USER>/Desktop" |
| DocumentsLocation | "~/Documents" | "C:/Users/<USER>/Documents" |
| FontsLocation | "~/Library/Fonts", "/Library/Fonts", "/System/Library/Fonts" | "C:/Windows/Fonts" (not writable) |
| ApplicationsLocation | "~/Applications", "/Applications" | "C:/Users/<USER>/AppData/Roaming/Microsoft/Windows/Start Menu/Programs" |
| MusicLocation | "~/Music" | "C:/Users/<USER>/Music" |
| MoviesLocation | "~/Movies" | "C:/Users/<USER>/Videos" |
| PicturesLocation | "~/Pictures" | "C:/Users/<USER>/Pictures" |
| TempLocation | randomly generated by the OS | "C:/Users/<USER>/AppData/Local/Temp" |
| HomeLocation | "~" | "C:/Users/<USER>" |
| AppLocalDataLocation | "~/Library/Application Support/<APPNAME>", "/Library/Application Support/<APPNAME>". "<APPDIR>/../Resources" | "C:/Users/<USER>/AppData/Local/<APPNAME>", "C:/ProgramData/<APPNAME>", "<APPDIR>", "<APPDIR>/data", "<APPDIR>/data/<APPNAME>" |
| CacheLocation | "~/Library/Caches/<APPNAME>", "/Library/Caches/<APPNAME>" | "C:/Users/<USER>/AppData/Local/<APPNAME>/cache" |
| StateLocation | "~/Library/Preferences/<APPNAME>/State" | "C:/Users/<USER>/AppData/Local/<APPNAME>/State", "C:/ProgramData/<APPNAME>/State" |
| GenericDataLocation | "~/Library/Application Support", "/Library/Application Support" | "C:/Users/<USER>/AppData/Local", "C:/ProgramData", "<APPDIR>", "<APPDIR>/data" |
| RuntimeLocation | "~/Library/Application Support" | "C:/Users/<USER>" |
| ConfigLocation | "~/Library/Preferences", "/Library/Preferences" | "C:/Users/<USER>/AppData/Local/<APPNAME>", "C:/ProgramData/<APPNAME>" |
| GenericConfigLocation | "~/Library/Preferences", "/Library/Preferences" | "C:/Users/<USER>/AppData/Local", "C:/ProgramData" |
| DownloadLocation | "~/Downloads" | "C:/Users/<USER>/Downloads" |
| GenericCacheLocation | "~/Library/Caches", "/Library/Caches", "/System/Library/Caches" | "C:/Users/<USER>/AppData/Local/cache" |
| GenericStateLocation | "~/Library/Preferences/State" | "C:/Users/<USER>/AppData/Local/State", "C:/ProgramData/State" |
| AppDataLocation | "~/Library/Application Support/<APPNAME>", "/Library/Application Support/<APPNAME>". "<APPDIR>/../Resources" | "C:/Users/<USER>/AppData/Roaming/<APPNAME>", "C:/ProgramData/<APPNAME>", "<APPDIR>", "<APPDIR>/data", "<APPDIR>/data/<APPNAME>" |
| AppConfigLocation | "~/Library/Preferences/<APPNAME>", "/Library/Preferences/<APPNAME>" | "C:/Users/<USER>/AppData/Local/<APPNAME>", "C:/ProgramData/<APPNAME>" |
| PublicShareLocation | "~/Public" | "C:/Users/Public" |
| TemplatesLocation | not supported | "C:/Users/<USER>/AppData/Roaming/Microsoft/Windows/Templates" |
| Path type | Linux and other UNIX operating systems |
|---|---|
| DesktopLocation | "~/Desktop" |
| DocumentsLocation | "~/Documents" |
| FontsLocation | "~/.fonts", "~/.local/share/fonts", "/usr/local/share/fonts", "/usr/share/fonts" |
| ApplicationsLocation | "~/.local/share/applications", "/usr/local/share/applications", "/usr/share/applications" |
| MusicLocation | "~/Music" |
| MoviesLocation | "~/Videos" |
| PicturesLocation | "~/Pictures" |
| TempLocation | "/tmp" |
| HomeLocation | "~" |
| AppLocalDataLocation | "~/.local/share/<APPNAME>", "/usr/local/share/<APPNAME>", "/usr/share/<APPNAME>" |
| CacheLocation | "~/.cache/<APPNAME>" |
| StateLocation | "~/.local/state/<APPNAME>" |
| GenericDataLocation | "~/.local/share", "/usr/local/share", "/usr/share" |
| RuntimeLocation | "/run/user/<USER>" |
| ConfigLocation | "~/.config", "/etc/xdg" |
| GenericConfigLocation | "~/.config", "/etc/xdg" |
| DownloadLocation | "~/Downloads" |
| GenericCacheLocation | "~/.cache" |
| GenericStateLocation | "~/.local/state" |
| AppDataLocation | "~/.local/share/<APPNAME>", "/usr/local/share/<APPNAME>", "/usr/share/<APPNAME>" |
| AppConfigLocation | "~/.config/<APPNAME>", "/etc/xdg/<APPNAME>" |
| PublicShareLocation | "~/Public" |
| TemplatesLocation | "~/Templates" |
| Path type | Android | iOS |
|---|---|---|
| DesktopLocation | "<APPROOT>/files" | "<APPROOT>/Documents/Desktop" |
| DocumentsLocation | "<USER>/Documents" [*], "<USER>/<APPNAME>/Documents" | "<APPROOT>/Documents" |
| FontsLocation | "/system/fonts" (not writable) | "<APPROOT>/Library/Fonts" |
| ApplicationsLocation | not supported (directory not readable) | not supported |
| MusicLocation | "<USER>/Music" [*], "<USER>/<APPNAME>/Music" | "<APPROOT>/Documents/Music" |
| MoviesLocation | "<USER>/Movies" [*], "<USER>/<APPNAME>/Movies" | "<APPROOT>/Documents/Movies" |
| PicturesLocation | "<USER>/Pictures" [*], "<USER>/<APPNAME>/Pictures" | "<APPROOT>/Documents/Pictures", "assets-library://" |
| TempLocation | "<APPROOT>/cache" | "<APPROOT>/tmp" |
| HomeLocation | "<APPROOT>/files" | system defined |
| AppLocalDataLocation | "<APPROOT>/files", "<USER>/<APPNAME>/files" | "<APPROOT>/Library/Application Support" |
| CacheLocation | "<APPROOT>/cache", "<USER>/<APPNAME>/cache" | "<APPROOT>/Library/Caches" |
| StateLocation | "<APPROOT>/files/state" | "<APPROOT>/Library/Preferences/<APPNAME>/State" |
| GenericStateLocation (there is shared state) | "<APPROOT>/files/state" | "<APPROOT>/Library/Preferences/State" |
| GenericDataLocation | "<USER>" [*] or "<USER>/<APPNAME>/files" | "<APPROOT>/Library/Application Support" |
| RuntimeLocation | "<APPROOT>/cache" | "<APPROOT>/Library/Application Support" |
| ConfigLocation | "<APPROOT>/files/settings" | "<APPROOT>/Library/Preferences" |
| GenericConfigLocation | "<APPROOT>/files/settings" (there is no shared settings) | "<APPROOT>/Library/Preferences" |
| DownloadLocation | "<USER>/Downloads" [*], "<USER>/<APPNAME>/Downloads" | "<APPROOT>/Documents/Downloads" |
| GenericCacheLocation | "<APPROOT>/cache" (there is no shared cache) | "<APPROOT>/Library/Caches" |
| AppDataLocation | "<APPROOT>/files", "<USER>/<APPNAME>/files" | "<APPROOT>/Library/Application Support" |
| AppConfigLocation | "<APPROOT>/files/settings" | "<APPROOT>/Library/Preferences/<APPNAME>" |
| PublicShareLocation | not supported | "<APPROOT>/Public" |
| TemplatesLocation | not supported | not supported |
In the table above, <APPNAME> is usually the organization name, the application name, or both, or a unique name generated at packaging. Similarly, <APPROOT> is the location where this application is installed (often a sandbox). <APPDIR> is the directory containing the application executable.
The paths above should not be relied upon, as they may change according to OS configuration, locale, or they may change in future Qt versions.
Note: On Android, applications with open files on the external storage (<USER> locations), will be killed if the external storage is unmounted.
Note: On Android 6.0 (API 23) or higher, the "WRITE_EXTERNAL_STORAGE" permission must be requested at runtime when using QStandardPaths::writableLocation or QStandardPaths::standardLocations.
Note: On Android, reading/writing to GenericDataLocation needs the READ_EXTERNAL_STORAGE/WRITE_EXTERNAL_STORAGE permission granted.
Note: [*] On Android 11 and above, public directories are no longer directly accessible in scoped storage mode. Thus, paths of the form "<USER>/DirName" are not returned. Instead, you can use QFileDialog which uses the Storage Access Framework (SAF) to access such directories.
Note: On iOS, if you do pass QStandardPaths::standardLocations(QStandardPaths::PicturesLocation).last() as argument to QFileDialog::setDirectory(), a native image picker dialog will be used for accessing the user's photo album. The filename returned can be loaded using QFile and related APIs. This feature was added in Qt 5.5.
See also writableLocation(), standardLocations(), displayName(), locate(), and locateAll().
Member Function Documentation
[static] QString QStandardPaths::displayName(QStandardPaths::StandardLocation type)
Returns a localized display name for the given location type or an empty QString if no relevant location can be found.
[static] QString QStandardPaths::findExecutable(const QString &executableName, const QStringList &paths = QStringList())
Finds the executable named executableName in the specified paths, or the system paths if paths is empty.
On most operating systems the system path is determined by the PATH environment variable. The directories where to search for the executable can be set in the paths argument. To search in both your own paths and the system paths, call findExecutable twice, once with paths set and once with paths empty. Symlinks are not resolved in order to preserve behavior for the case of executables whose behavior depends on the name they are invoked with.
Note: On Windows, the usual executable extensions (from the PATHEXT environment variable) are automatically appended. For example, the findExecutable("foo") call finds foo.exe or foo.bat if present.
Returns the absolute file path to the executable, or an empty string if not found.
If the given executableName is an absolute path pointing to an executable, its clean path is returned.
[static] QString QStandardPaths::locate(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile)
Finds a file or directory called fileName in the standard locations for type.
The options flag lets you specify whether to look for files or directories. By default, this flag is set to LocateFile.
Returns the absolute path to the first file or directory found, otherwise returns an empty string.
[static] QStringList QStandardPaths::locateAll(QStandardPaths::StandardLocation type, const QString &fileName, QStandardPaths::LocateOptions options = LocateFile)
Finds all files or directories by the name, fileName, in the standard locations for type.
The options flag lets you specify whether to look for files or directories. By default, this flag is set to LocateFile.
Returns the list of all the files that were found.
[static] void QStandardPaths::setTestModeEnabled(bool testMode)
If testMode is true, this enables a special "test mode" in QStandardPaths, which changes writable locations to point to test directories. This prevents auto tests from reading or writing to the current user's configuration.
It affects the locations into which test programs might write files: GenericDataLocation, AppDataLocation, ConfigLocation, GenericConfigLocation, AppConfigLocation, StateLocation, GenericStateLocation, GenericCacheLocation, and CacheLocation. Other locations are not affected.
On Unix, XDG_DATA_HOME is set to ~/.qttest/share, XDG_CONFIG_HOME is set to ~/.qttest/config, XDG_STATE_HOME is set ~/.qttest/state and XDG_CACHE_HOME is set to ~/.qttest/cache.
On macOS, data goes to ~/.qttest/Application Support, cache goes to ~/.qttest/Cache, and config goes to ~/.qttest/Preferences.
On Windows, everything goes to a "qttest" directory under %APPDATA%.
[static] QStringList QStandardPaths::standardLocations(QStandardPaths::StandardLocation type)
Returns all the directories where files of type belong.
The list of directories is sorted from high to low priority, starting with writableLocation() if it can be determined. This list is empty if no locations for type are defined.
See also writableLocation().
[static] QString QStandardPaths::writableLocation(QStandardPaths::StandardLocation type)
Returns the directory where files of type should be written to, or an empty string if the location cannot be determined.
Note: The storage location returned may not exist; that is, it may need to be created by the system or the user.
© 2026 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.
