Modern QML modules | Qt Qml 6.8.3
Description: Modernize your QML modules.

- Qt 6.8
- Qt Qml
- Modern QML modules
- Qt 6.8.3 Reference Documentation

# Modern QML modules

QML modules have become more powerful and easier to use in Qt 6. The following sections describe how to modernize QML modules that already use qt_add_qml_module.

See also Port QML modules to CMake on how to port a QML module to the qt_add_qml_module CMake API.

## Use qt_standard_project_setup

qt_standard_project_setup sets up Qt CMake policies needed for modern QML modules, among other things. To modernize your QML module and follow best practices, call qt_standard_project_setup in the project's top-level `CMakeLists.txt` file before any qt_add_qml_module call:

     qt_standard_project_setup(REQUIRES 6.8)

## Use the new standard resource path prefix

The standard resource path for QML modules moved from `:/` to `:/qt/qml` with QTP0001. Don't use custom resource prefixes nor extend import paths in the engine. Remove all `RESOURCE_PREFIX` arguments from all qt_add_qml_module calls, as well as all calls to QQmlEngine::addImportPath or similar. Change all qrc paths in your C++ and QML code to use the new resource path prefix:

     // C++ usages like:
     QUrl someUrl("qrc:/MyQmlModule/MyResource1.png");
     // need to be changed to
     QUrl someUrl("qrc:/qt/qml/MyQmlModule/MyResource1.png");

     // QML usages like:
     ":/MyQmlModule/MyResource1.png"
     // need to be changed to
     ":/qt/qml/MyQmlModule/MyResource1.png"

See also Using the Qt Resource System with QML.

## Use loadFromModule to load your QML files

With the default import path, you can use the `loadFromModule` methods, like QQmlApplicationEngine::loadFromModule, QQuickView::loadFromModule, or QQmlComponent::loadFromModule, for example.

Use `loadFromModule` to load your QML file, for example:

     engine.load(QUrl(QStringLiteral("qrc:/MyQmlModule/Main.qml")));
     // becomes
     engine.loadFromModule("MyQmlModule", "Main");

## Replace OUTPUT_DIRECTORY and IMPORT_PATH with DEPENDENCIES TARGET

Avoid setting an `IMPORT_PATH` in the qt_add_qml_module. Instead, use `DEPENDENCIES TARGET` to declare dependencies to other QML modules that can't be found in the current import path.

Using `DEPENDENCIES TARGET` also eliminates the need for the `QT_QML_OUTPUT_DIRECTORY` CMake variable and the `OUTPUT_DIRECTORY` argument to qt_add_qml_module, so remove their definitions and usages.

For example:

     ### in the CMakeLists.txt file defining the dependent QML module:
     # don't set QT_QML_OUTPUT_DIRECTORY and remove lines like these:
     set(QT_QML_OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/qml)

     qt_add_qml_module(MyThirdPartyQmlLibraryDependency
         URI MyThirdPartyQmlLibraryDependency
         ....
         # custom output paths are obsolete due to DEPENDENCIES TARGET below, so remove:
         OUTPUT_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/qml
     }

     ### in the CMakeLists.txt file defining the QML module that uses the dependency:
     qt_add_qml_module(MyQmlLibrary
         URI MyQmlModule
         ...
         # replace import paths like these:
         IMPORT_PATH ${CMAKE_CURRENT_BINARY_DIR}/thirdparty/qml
         # with:
         DEPENDENCIES TARGET MyThirdPartyQmlLibraryDependency
     }

Note: You might need to call `add_subdirectory()` before calling qt_add_qml_module in your CMakeLists.txt for `DEPENDENCIES TARGET` to find the target.

For more information on how to declare module dependencies, see Declaring module dependencies.

See also Changes to Qt QML and Port QML modules to CMake.