如何实现无额外依赖的Pythonic跨平台应用单实例运行

完全不需要额外安装tendo这类第三方库，直接利用PyQt5自带的跨平台文件锁能力即可实现单实例校验，原生兼容Windows、macOS、Linux系统，完全符合日常桌面应用的使用要求。

核心实现逻辑 #

PyQt5自带的QLockFile模块是Qt官方封装的跨平台进程锁工具，本质是基于操作系统原生的锁机制实现：

• 程序首次启动时，在系统公共临时目录下创建和应用绑定的独占锁文件，获取锁的持有权
• 第二次重复启动程序时，尝试获取锁会立即失败，直接终止重复实例的运行
• 程序正常退出时锁会自动释放；就算程序异常崩溃，操作系统也会自动回收对应的锁资源，不会出现锁残留导致的启动失效问题

适配原有代码的完整示例 #

直接在现有PyQt5代码的启动入口加入单实例判断逻辑即可，不需要改动原有窗口类的任何实现：

import sys
from PyQt5.QtWidgets import *
from PyQt5.QtCore import QLockFile, QDir


class Window(QWidget):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Using Labels")
        self.setGeometry(50, 50, 350, 350)
        self.UI()

    def UI(self):
        text1 = QLabel("Hello Python", self)
        text2 = QLabel("Hello World", self)
        text1.move(50, 50)
        text2.move(200, 150)
        self.show()


def main():
    App = QApplication(sys.argv)

    # 单实例校验核心逻辑
    # 锁文件名需要设置为应用独有的唯一标识，避免和其他应用冲突
    lock_file_path = QDir.tempPath() + "/pyqt5_single_instance_demo.lock"
    lock = QLockFile(lock_file_path)
    # 非阻塞尝试获取锁，超时时间设为0，获取失败立即返回
    is_locked = lock.tryLock(0)
    if not is_locked:
        QMessageBox.information(None, "提示", "应用已经在运行了")
        return
    # 把锁对象绑定到QApplication实例上，避免被垃圾回收导致锁提前释放
    App._single_instance_lock = lock

    window = Window()
    sys.exit(App.exec_())


if __name__ == '__main__':
    main()

关键注意事项 #

• 锁的引用必须绑定到长期存活的对象（比如上面代码里的App实例），不能作为临时局部变量存在，否则局部变量出栈后会被Python垃圾回收，锁会提前释放，失去单实例校验的作用
• 锁文件的命名要足够唯一，可以自定义带应用专属标识的字符串，不要用通用名称（比如app.lock），避免和其他应用的锁文件重名冲突
• 不需要手动删除锁文件，QLockFile会在程序退出、锁对象销毁时自动清理临时文件，就算程序异常退出，操作系统也会自动回收对应的进程锁资源

纯Windows场景的补充实现 #

如果完全不需要跨平台兼容，也可以直接通过Python标准库ctypes调用Windows原生的命名互斥量接口实现单实例校验，同样零依赖，但这种写法无法在macOS、Linux上运行，适合只面向Windows发布的精简场景。

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