Migrate from PySide2 to PySide6 to Fix Qt Symbol Compatibility Issues

[stephanschielke]

Problem Statement

PhotoGlimmer users on modern Ubuntu systems (particularly Ubuntu 24.04 with Python 3.12) were encountering critical import errors that prevented the application from starting:

ImportError: /path/to/PySide2/QtUiTools.abi3.so: undefined symbol: _ZdlPvm, version Qt_5

This error occurs due to ABI (Application Binary Interface) incompatibilities between PySide2's Qt 5 libraries and the system's Qt libraries, which is a common issue on newer Linux distributions where Qt library versions may conflict.

Root Cause Analysis

The _ZdlPvm, version Qt_5 symbol error indicates that PySide2 was built against a different version of Qt than what's available on the system, creating binary compatibility issues. This problem is exacerbated by:

1. System Qt Libraries: Modern Ubuntu installations include newer Qt versions that may not be fully compatible with PySide2's expectations
2. OpenCV Conflicts: The opencv-contrib-python package includes its own Qt libraries that can conflict with PySide2
3. Python Version Compatibility: Newer Python versions (3.12+) have stricter ABI requirements that PySide2 may not fully satisfy

Solution: Migration to PySide6

PySide6 provides better compatibility with modern systems and resolves these ABI conflicts because:

• It's actively maintained and updated for newer Qt versions
• Better integration with modern Linux distributions
• Improved Python 3.12+ compatibility
• More robust handling of system Qt library conflicts

Changes Made

1. Dependency Updates

• Requirements: PySide2~=5.15 → PySide6~=6.5
• Build Configuration: Updated pyproject.toml dependencies
• OpenCV: Switched to opencv-contrib-python-headless==4.8.1.78 to eliminate Qt conflicts

2. Import Statement Migration

Updated import statements across all Python files:

# Before (PySide2)
from PySide2.QtWidgets import QApplication, QMainWindow
from PySide2.QtCore import QThread, QTimer
from PySide2.QtGui import QPixmap, QIcon

# After (PySide6)  
from PySide6.QtWidgets import QApplication, QMainWindow
from PySide6.QtCore import QThread, QTimer
from PySide6.QtGui import QPixmap, QIcon

3. API Compatibility Fixes

• QAction Migration: In PySide6, QAction moved from QtWidgets to QtGui
• Fixed import statements in photoglimmer_ui.py and other affected files

4. Files Modified

• src/photoglimmer/photoglimmer_ui.py - Main UI imports and QAction fix
• src/photoglimmer/customfiledialog.py - File dialog imports
• src/photoglimmer/imagewidget.py - Image widget imports
• src/photoglimmer/colorcurverwidget.py - Color curve widget imports
• src/photoglimmer/threadwork.py - Threading imports
• src/photoglimmer/uihelper_transparency.py - UI helper imports + indentation fixes
• src/photoglimmer/prefs/settings_config.py - Settings imports
• src/photoglimmer/prefs/preferences_dialog.py - Preferences imports
• src/photoglimmer/requirements.txt - Dependency updates
• pyproject.toml - Build configuration updates

Testing Results

✅ Application Startup: PhotoGlimmer now starts successfully on Ubuntu 24.04 with Python 3.12
✅ Core Functionality: All photo editing features work as expected
✅ UI Rendering: No visual regressions, all Qt widgets render correctly
✅ File Operations: Image loading, saving, and processing work without issues
✅ Backwards Compatibility: Existing user preferences and workflows preserved

Benefits of This Migration

1. Improved Stability: Eliminates Qt symbol conflicts on modern Linux systems
2. Future-Proof: PySide6 is actively maintained and supports newer Qt versions
3. Better Performance: PySide6 includes performance improvements over PySide2
4. Modern Python Support: Full compatibility with Python 3.12+
5. Reduced Dependencies: Using opencv-contrib-python-headless reduces potential conflicts

Migration Impact

• User Impact: Minimal - existing workflows and UI remain unchanged
• Developer Impact: Future development can leverage PySide6's newer features
• System Requirements: Better compatibility with modern Ubuntu/Linux systems
• Installation: Smoother installation process with fewer dependency conflicts

This migration ensures PhotoGlimmer remains accessible to users on modern Linux systems while maintaining all existing functionality and improving overall stability.

[codecliff]

@stephanschielke Hi! Thanks a lot for your contribution looking at it and will revert to you over the weekend,

[codecliff]

@stephanschielke Hi! I've pulled your code into (a new branch of) my local repository. It does port the code successfully to Pyside6 and that is something I appreciate a lot. Let me go over all the modalities of supporting specific versions of Qt on various platforms with minimal dependency leakages . The status of pull request will change only after I am done with all the changes and testing and merged it to master. That might take some time. Again, thanks for the contribution.