PAYATHON 2026

Python/PySide6 项目中如何配置 Qt Creator 的 QML 导入路径？

数据小许

先查询项目 venv 中 PySide6 使用的 QML 模块目录，再将其配置给 Qt Creator 启动的 qmlls。可以优先使用项目根目录下的 .qmlls.ini，通过 importPaths 设置导入路径。

只修改项目的运行环境，不能保证编辑器的语言服务器也使用同样的配置。题目没有给出 PySide6 和 qmlls 的具体版本，还需要核对实际启动的工具及其支持的选项。

为什么运行正常，编辑器却找不到模块？

Python 应用和编辑器中的 qmlls 是不同的进程。应用可以从 PySide6 的 Qt 安装目录找到模块，而编辑器可能仍在使用另一套 Qt 的搜索路径。

题目显示，Python 项目的编辑器只搜索 C:\Qt\Tools\QtCreator\bin\qml。既然应用能够正常运行，可以先排查编辑器的模块路径和工具选择。

通过 Maintenance Tool 安装的模块、C++/MinGW Kit 使用的模块，以及当前 venv 中 PySide6 使用的模块，不能直接视为同一套安装。QML 引擎的默认导入路径包含 QLibraryInfo::QmlImportsPath，可以据此查询当前 Python 环境对应的位置。Qt QML 导入路径说明

1. 查询当前 venv 的 QML 模块目录

使用 Qt Creator 为该项目选择的 venv 解释器运行以下代码：

import sys
from pathlib import Path

import PySide6
from PySide6.QtCore import QLibraryInfo, qVersion

qml_path = Path(
    QLibraryInfo.path(QLibraryInfo.LibraryPath.QmlImportsPath)
)

print("Python:", sys.executable)
print("PySide6:", PySide6.__version__)
print("Qt:", qVersion())
print("QML imports:", qml_path)

for module in ("QtGraphs", "QtCharts"):
    module_dir = qml_path / module
    print(module, "qmldir exists:", (module_dir / "qmldir").is_file())

确认 Python 的输出与项目配置一致，并记录 QML imports 的实际结果，不要仅凭目录名称猜测路径。QLibraryInfo API

检查 qmldir 只能确认指定目录下是否存在模块描述文件，不能证明插件一定可加载或所有类型都能补全。如果文件不存在，应继续核对该 venv 的 PySide6 安装内容和版本，不要指向另一个环境来掩盖问题。

2. 在项目根目录配置 .qmlls.ini

创建 .qmlls.ini 文件，注意文件名前面的点。假设上一步得到的路径是下面的示例目录，可以这样写：

[General]
importPaths=C:/work/MyApp/.venv/Lib/site-packages/PySide6/qml
no-cmake-calls=true

将示例路径替换为实际输出。路径应指向同时包含 QtGraphs、QtCharts 等模块目录的 QML 导入根目录，而不是某个模块的子目录。

importPaths 用于配置模块搜索位置。对于不需要调用 CMake 的 Python 项目，可以用 no-cmake-calls=true 关闭 qmlls 的自动 CMake 调用。不要为了填写配置而虚构 buildDir。

配置项及项目根目录的位置要求见 QML Language Server 配置文档。保存后重启语言服务器；如果当前界面没有重启入口，可以关闭并重新打开 Qt Creator。

3. 核对 Qt Creator 实际使用的 qmlls

Qt Creator 的版本号不能代替 qmlls 的版本号。检查 QML Language Server 设置和相关日志，确认实际启动的是哪个可执行文件。

Qt Creator 可以选择使用项目 Qt Kit 中的 qmlls、其他 Kit 中的 qmlls，或自定义可执行文件。具体选项以当前安装版本为准。Qt Creator 的 QML Language Server 设置

如果 venv 中存在 pyside6-qmlls.exe，可以先查看其帮助，再考虑将它配置为自定义语言服务器：

& "C:/work/MyApp/.venv/Scripts/pyside6-qmlls.exe" --help

这个路径也是示例。不要假设每个安装环境都有此文件，也不要在可执行文件路径输入框中直接追加命令行参数。

4. 配置未生效时检查参数和环境变量

如果所用 qmlls 支持 -I，且语言客户端提供独立的参数配置入口，可以显式传入导入目录。对应的启动形式为：

& "C:/path/to/qmlls.exe" -I "C:/work/MyApp/.venv/Lib/site-packages/PySide6/qml" --no-cmake-calls

这展示的是语言客户端启动 qmlls 时的参数形式。单独在终端执行该命令，不会自动让 Qt Creator 连接该进程。

还需留意版本差异。Qt 6.8 的官方文档明确说明，通过 QML_IMPORT_PATH 环境变量传入路径时，需要给 qmlls 添加 -E。同一配置由多处提供时，命令行参数优先于环境变量，环境变量优先于配置文件，因此也要检查启动参数是否覆盖了 .qmlls.ini。Qt 6.8 qmlls 导入路径配置

如果采用环境变量方式，变量必须传给 qmlls 进程。只在项目的 Run Environment 中设置它，通常只会影响运行的应用，不能保证影响编辑器服务。

5. 仍有红线时确认诊断来源

Qt Creator 可以同时使用 qmlls 和内置 QML code model。报错中出现 qmake 提示，不足以证明该条诊断一定来自 qmlls。

如果已确认 qmlls 收到了正确路径，但原报错仍在，应查看诊断来源和语言服务器日志，判断是否还有内置 code model 的诊断。必要时执行 Tools > QML/JS > Reset Code Model；实际菜单位置以安装版本为准。Qt Creator 模块识别与 code model 说明

如果模块已经能找到，但个别类型仍无法补全，再检查模块提供的 .qmltypes 类型描述文件及工具版本兼容性。路径已识别不代表所有补全功能都已验证。

保持当前正常运行的 Python 启动方式即可。无需为了修复编辑器提示而改成 C++ 项目，也无需先修改应用中的 engine.addImportPath()；应先让编辑器使用与当前 PySide6 环境对应的模块路径。

备注：内容仅供参考。