PyQt6环境下QtVirtualKeyboard的正确安装方式及部署疑问

通用设置 #

我参考StackOverflow的一篇回答安装了QtVirtualKeyboard，执行的具体命令如下：

python3 -m venv venv
venv/bin/pip install -U pip wheel PyQt6 aqtinstall
QT_PREFIX_PATH=$(venv/bin/python -c "from PyQt6.QtCore import QLibraryInfo; print(QLibraryInfo.path(QLibraryInfo.LibraryPath.PrefixPath), end=None)")
QT_VERSION_STR=$(venv/bin/python -c "from PyQt6.QtCore import QT_VERSION_STR; print(QT_VERSION_STR, end=None)")
QT_VERSION_STR=6.7.3
venv/bin/python -m aqt install-qt linux desktop $QT_VERSION_STR -m qtvirtualkeyboard --outputdir qt
cp -p qt/$QT_VERSION_STR/gcc_64/lib/libQt6VirtualKeyboard.so.$QT_VERSION_STR $QT_PREFIX_PATH/lib/libQt6VirtualKeyboard.so.6
cp -p qt/$QT_VERSION_STR/gcc_64/lib/libQt6VirtualKeyboardSettings.so.$QT_VERSION_STR $QT_PREFIX_PATH/lib/libQt6VirtualKeyboardSettings.so.6
mkdir -p $QT_PREFIX_PATH/plugins/platforminputcontexts
cp -p qt/$QT_VERSION_STR/gcc_64/plugins/platforminputcontexts/libqtvirtualkeyboardplugin.so $QT_PREFIX_PATH/plugins/platforminputcontexts
#cp -pr qt/$QT_VERSION_STR/gcc_64/plugins/virtualkeyboard $QT_PREFIX_PATH/plugins
cp -pr qt/$QT_VERSION_STR/gcc_64/qml/QtQuick/VirtualKeyboard $QT_PREFIX_PATH/qml/QtQuick
mkdir -p $QT_PREFIX_PATH/qml/Qt/labs
cp -pr qt/$QT_VERSION_STR/gcc_64/qml/Qt/labs/folderlistmodel $QT_PREFIX_PATH/qml/Qt/labs

注： 我不得不强制设置QT_VERSION_STR=6.7.3，因为使用Python脚本获取的6.7.1版本会导致运行时错误（提示找不到6.7.3版本），这是否暗示我的设置存在问题？

测试程序代码如下：

from PyQt6.QtWidgets import QApplication, QWidget, QMainWindow, QLineEdit, QVBoxLayout

import sys
import os
os.environ["QT_IM_MODULE"] = "qtvirtualkeyboard"

class MaiWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.line_edit = QLineEdit()
        self.line_edit2 = QLineEdit()
        self.layout = QVBoxLayout()
        self.main_widget = QWidget()
        self.main_widget.setLayout(self.layout)
        self.layout.addWidget(self.line_edit)
        self.layout.addWidget(self.line_edit2)
        self.setCentralWidget(self.main_widget)


app = QApplication(sys.argv)

window = MaiWindow()
window.show()

app.exec()

使用venv.hide/bin/python test.py启动程序后，聚焦QLineEdit时可正常显示虚拟键盘。

问题1 #

最核心的疑问：这是安装QtVirtualKeyboard的正确方式吗？该方式看起来十分繁琐，我担心后续完成应用部署时会出现问题。

回答 #

你的安装方式不是官方推荐的标准流程，手动复制文件的操作确实容易在部署阶段引发问题，具体原因和优化方案如下：

1. 版本不匹配的本质
   你遇到的QT_VERSION_STR强制设置问题，根源是PyQt6的编译依赖版本和脚本获取的版本不一致。PyQt6的QT_VERSION_STR返回的是它编译时依赖的Qt版本，而你必须指定6.7.3才能运行，说明你安装的PyQt6实际依赖Qt 6.7.3，脚本获取的6.7.1是异常值——大概率是虚拟环境路径识别问题导致读取错误。

2. 更可靠的安装与使用方式
   官方推荐两种场景的集成方案：

• 开发阶段：通过aqtinstall安装对应版本的Qt及虚拟键盘组件后，直接设置环境变量让PyQt6调用，无需手动复制文件：

  # 创建并激活虚拟环境
  python3 -m venv venv
  source venv/bin/activate
  # 安装依赖
  pip install -U pip wheel PyQt6 aqtinstall
  # 获取PyQt6实际依赖的Qt版本（若脚本获取异常，可通过pip show PyQt6查看Qt Version字段）
  QT_VERSION=$(pip show PyQt6 | grep -oP 'Qt Version: \K.*')
  # 安装对应版本的Qt及虚拟键盘组件
  python -m aqt install-qt linux desktop $QT_VERSION -m qtvirtualkeyboard --outputdir qt
  # 设置环境变量，让PyQt6指向该Qt环境
  export QTDIR=./qt/$QT_VERSION/gcc_64
  export LD_LIBRARY_PATH=$QTDIR/lib:$LD_LIBRARY_PATH
  export QT_PLUGIN_PATH=$QTDIR/plugins:$QT_PLUGIN_PATH
  export QML2_IMPORT_PATH=$QTDIR/qml:$QML2_IMPORT_PATH
  

  直接在该环境下运行测试程序即可，无需修改PyQt6的目录结构。

• 部署阶段：使用PyInstaller等打包工具时，通过参数直接引入所需组件，避免手动复制的混乱：

  pyinstaller --onefile \
    --add-data "./qt/$QT_VERSION/gcc_64/plugins/platforminputcontexts/libqtvirtualkeyboardplugin.so:./plugins/platforminputcontexts" \
    --add-data "./qt/$QT_VERSION/gcc_64/qml/QtQuick/VirtualKeyboard:./qml/QtQuick/VirtualKeyboard" \
    --add-data "./qt/$QT_VERSION/gcc_64/qml/Qt/labs/folderlistmodel:./qml/Qt/labs/folderlistmodel" \
    --env "QT_IM_MODULE=qtvirtualkeyboard" \
    test.py
  

  打包后的程序会自动包含所有必需组件，无需依赖外部Qt环境。

3. 手动复制方式的风险
   当前手动复制文件的操作可能破坏PyQt6原有文件结构，后续升级PyQt6或Qt版本时极易出现版本冲突、文件丢失等问题；同时部署时需要复制大量零散文件，打包流程会变得复杂且容易出错。

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