如何解决PySide项目中QML引用QtLocation模块未安装的报错？

问题场景 #

在Qt Creator中实现了一个显示简易地图的应用，现在需要在不使用WebEngine的PySide6项目中复刻相同功能，使用了如下QML和Python代码，但运行时提示错误module "QtLocation" is not installed。

原QML代码 #

import QtQuick 2.0
import QtPositioning 5.5
import QtLocation 5.6
import QtQuick.Controls 2.0

Item
{
id: root
visible: true

Plugin
{
    id: osmPlug
    name: "osm"
    
    PluginParameter
    {
        name: "osm.mapping.providersrepository.disabled"
        value: "true"
    }
    PluginParameter
    {
        name: "osm.mapping.providersrepository.address"
        value: "http://maps-redirect.qt.io/osm/5.6/"
    }
}

Map
{
    id: map
    anchors.fill: parent
    plugin: osmPlug
    center: QtPositioning.coordinate(59.91, 10.75) // Oslo
    zoomLevel: 3
    copyrightsVisible: false
    fieldOfView: 15
}
}

原Python代码 #

# This Python file uses the following encoding: utf-8
import sys
from pathlib import Path

from PySide6.QtGui import QGuiApplication
from PySide6.QtQml import QQmlApplicationEngine


if __name__ == "__main__":
    app = QGuiApplication(sys.argv)
    engine = QQmlApplicationEngine()
    qml_file = Path(__file__).resolve().parent / "main.qml"
    engine.load(qml_file)
    if not engine.rootObjects():
        sys.exit(-1)
    sys.exit(app.exec())

解决方案 #

1. 安装完整的PySide6模块 #

PySide6默认安装可能不包含QtLocation、QtPositioning这类附加模块，需要安装完整版本：

pip install PySide6[full]

2. 统一QML导入版本与PySide6版本 #

原QML中使用的是Qt5版本的导入语句（QtPositioning 5.5、QtLocation 5.6），但PySide6基于Qt6，版本不匹配会导致模块无法识别。修改导入语句为Qt6对应版本：

import QtQuick 6.0
import QtPositioning 6.0
import QtLocation 6.0
import QtQuick.Controls 6.0

也可以省略版本号，让QML自动匹配当前PySide6对应的Qt版本：

import QtQuick
import QtPositioning
import QtLocation
import QtQuick.Controls

3. 安装系统级依赖库 #

不同系统需要确保QtLocation相关的运行库已安装：

• Linux（Debian/Ubuntu）：

  sudo apt install libqt6location6 libqt6positioning6
  

• macOS（使用Homebrew）：

  brew install qt6-location
  

• Windows：确保安装PySide6时已包含所有依赖，若仍有问题，可重新运行pip install PySide6[full]并检查安装日志。

4. 适配Qt6的OSM插件配置 #

Qt6中OSM插件的参数与Qt5不同，原有的providersrepository相关参数已不再需要，简化Plugin部分代码：

Plugin {
    id: osmPlug
    name: "osm"
}

如果需要自定义地图瓦片源，可以使用Qt6支持的参数，例如：

Plugin {
    id: osmPlug
    name: "osm"
    PluginParameter {
        name: "osm.mapping.custom.host"
        value: "https://tile.openstreetmap.org/"
    }
}

修改后的完整代码 #

QML代码（main.qml） #

import QtQuick
import QtPositioning
import QtLocation
import QtQuick.Controls

Item {
    id: root
    visible: true

    Plugin {
        id: osmPlug
        name: "osm"
    }

    Map {
        id: map
        anchors.fill: parent
        plugin: osmPlug
        center: QtPositioning.coordinate(59.91, 10.75) // Oslo
        zoomLevel: 3
        copyrightsVisible: false
        fieldOfView: 15
    }
}

Python代码 #

# This Python file uses the following encoding: utf-8
import sys
from pathlib import Path

from PySide6.QtGui import QGuiApplication
from PySide6.QtQml import QQmlApplicationEngine


if __name__ == "__main__":
    app = QGuiApplication(sys.argv)
    engine = QQmlApplicationEngine()
    qml_file = Path(__file__).resolve().parent / "main.qml"
    engine.load(qml_file)
    if not engine.rootObjects():
        sys.exit(-1)
    sys.exit(app.exec())

内容的提问来源于stack exchange，提问作者user17312099