Skip to main content

FAQ

Q1. How do I install the module?​

A: Use pip install QT-PyQt-PySide-Custom-Widgets to install for the first time. To upgrade, run pip install --upgrade QT-PyQt-PySide-Custom-Widgets. ([PyPI][1]) Make sure your Python version and Qt binding (PyQt or PySide) versions are compatible.

Q2. Why don’t my custom widgets show up in Qt Designer?​

A:

  • Ensure you have the correct plugin path set (so Designer knows where to find the custom widgets).
  • Make sure you ran the --convert-ui or the equivalent build step (if required) so that the .ui files referencing custom widgets resolve correctly. ([Khamisi Kibet][2])
  • Check if the widgets are compatible with your Qt binding (PySide6 vs PyQt5/6) and version.
  • If they still don’t show, check for missing dependencies (see next question).

Q3. I get an error like OSError: no library called "libcairo.so.2" or similar. What’s wrong?​

A: This may occur when using modules inside the custom-widgets package that rely on external libraries (e.g., cairosvg which in turn uses cairo). For example:

OSError: no library called "cairo-2" was found

([Stack Overflow][3]) Solution:

  • On Windows, ensure libcairo-2.dll exists and is in your PATH (or installed via a binary distribution). ([Qt Forum][4])
  • On Linux/macOS, install the platform package (e.g., sudo apt-get install libcairo2-dev or equivalent).
  • Alternatively, if you don’t need the feature depending on Cairo, try disabling it or using a simpler widget that doesn’t require that library.

Q4. I’m seeing a deprecation warning: sipPyTypeDict() is deprecated…. Should I worry?​

A: Deprecation warnings such as:

UserWarning: Deprecated imports. For more information, refer to the documentation…

or

sipPyTypeDict() is deprecated, the extension module should use sipPyTypeDictRef() instead

have been reported. ([Reddit][5]) Answer: These warnings are not fatal — your code will likely still run. But they indicate that underlying libraries (SIP, PyQt/PySide) will remove support in future versions. What you can do:

  • Ensure you’re using a supported Python version (e.g., 3.10-3.11) and compatible Qt binding.
  • Monitor for module updates.
  • If the warning bothers you, consider using a version of PyQt or PySide that uses newer SIP versions.

Q5. My layout is broken (widgets overlap or don’t resize) when I add custom widgets to my main window.​

A: This is a common Qt layout issue when using custom widgets. For proper resizing and positioning:

  • Ensure your custom widget’s internal contents are managed by layouts (i.e., QVBoxLayout, QHBoxLayout, etc). If child widgets are placed without a layout, they may not respond to parent resizing. ([Python GUIs Forum][6])
  • In Designer, make sure the main container has a layout set and no “red” warnings.
  • After placing the custom widget, check the parent layout and properties (stretch, size policies) to ensure expected behavior.

Q6. I used an older version of the module in an existing GUI app, and now upgrading causes errors. How do I update without rewriting everything?​

A: Good that you asked. The module documentation outlines a migration path for older GUI apps (pre v0.6.8) to the newer module structure. ([Khamisi Kibet][2]) Steps summary:

  • Upgrade to the latest version via pip install --upgrade ….
  • Create a fresh project scaffold using the Custom_Widgets --create-project tool (if provided).
  • Copy your old UI, source and resource files according to the new folder structure (ui/, src/, qss/, logs/, json_styles/, generated-files/).
  • Exclude old generated files (ui_.py, rc_.py, icons generated by the module) to avoid conflicts.
  • Rebuild or convert UI files (Custom_Widgets --convert-ui …).
  • Run and test. Fix any deprecated API usage or changed widget names.

Q7. Can I use only PyQt (or only PySide) with this package?​

A: Yes — the package supports both PyQt and PySide (depending on your choice). However:

  • Verify compatibility of the widgets with your chosen binding (some widgets may assume PySide6).
  • When converting UI or running the project-maker tool, specify the Qt library correctly (e.g., --qt-library your-lib) if required. ([Khamisi Kibet][2]) If you run into issues (#133 on GitHub mentions “How to use only PyQt5 with Project Builder/Project Setup Wizard”). ([GitHub][7])

Q8. How do I use the custom widgets inside Qt Designer and then reference them in my PySide6/PyQt code?​

A: In summary:

  1. In Qt Designer, add the custom widgets from the module (after the Designer plugin or promotion setup).
  2. Save the .ui file.
  3. Use the module’s conversion tool (or pyuic/pyside6-uic) to generate the Python file (e.g., ui_mainwindow.py).
  4. In your code, import the generated UI class and the custom widget module, then load the UI.
  5. Ensure your sys.path includes the module so that the custom widgets are importable. Tip: Always run the module’s examples (in examples/ folder of the repo) to verify that your environment is working. ([GitHub][8])

Q9. I changed the theme/style JSON or SCSS in the module but the app still shows the old style.​

A:

  • Check if you have enabled “live compile” of QSS/SCSS via LiveCompileQss: true in your style JSON. Without this, you may need to restart your app for changes to apply. ([PyPI][9])
  • Make sure the JSON style file is in the correctly-named folder (json_styles/ by default).
  • Verify that the qml, qss, scss folder structure is correct and that the generated-files or icons folder isn’t overwriting your changes.
  • Clear the generated-files/ folder and let the module regenerate resources if necessary.

Q10. Where can I report bugs or request features?​

A: You can open an issue on the GitHub repository (see the Issues tab of the repository). ([GitHub][7]) Also check the Discussions tab for community Q&A. Before filing a bug:

  • Search existing issues (some common ones are already listed).
  • Provide steps to reproduce, your environment (OS, Python version, PyQt/PySide version), and a minimal code/sample.
  • For feature requests, describe your use-case and why the change helps your GUI.

Advanced FAQs​

Q11. How do I dynamically load .ui files at runtime instead of converting them to Python code?​

If you prefer to load .ui files directly without running pyuic or pyside6-uic, you can do:

from PySide6 import QtUiTools
from PySide6.QtWidgets import QMainWindow

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        loader = QtUiTools.QUiLoader()
        ui = loader.load("path/to/ui_file.ui", self)
        self.setCentralWidget(ui)

Make sure your custom widgets are registered with the QUiLoader before loading, or Designer-promoted widgets will fail. For example:

loader.registerCustomWidget(MyCustomWidget)

This is useful for projects where you want to support live UI updates or plugin architectures.

Q12. Can I use relative resource paths in the generated UI files?​

Yes. To make resources portable, always use resource aliases or dynamically resolve paths. Avoid hardcoding absolute paths like:

self.icon = QIcon("/home/user/project/icons/app.png")

Instead, use:

from pathlib import Path
icon_path = Path(__file__).resolve().parent / "icons/app.png"
self.icon = QIcon(str(icon_path))

In larger apps, integrate a resource_manager.py that detects the correct base directory whether the app is running in development or as a packaged binary (PyInstaller, cx_Freeze, etc.).

Q13. My PyInstaller or fbs build fails after adding custom widgets. How do I fix missing assets?​

This often happens because PyInstaller does not automatically collect the qss, json_styles, or generated-files directories. Add a custom hook file:

# hook-qt_pyqt_pyside_custom_widgets.py
from PyInstaller.utils.hooks import collect_data_files
datas = collect_data_files('QT_PyQt_PySide_Custom_Widgets')

Then rebuild:

pyinstaller main.spec

Also ensure that dynamically loaded assets (QSS, icons, JSON) are either copied manually in your .spec file or loaded via a resource system.

Q14. How do I register a custom widget in Qt Designer so it appears in the widget box?​

Qt Designer does not automatically recognize Python-based widgets unless you create a plugin. Steps:

  1. Create a subclass of QDesignerCustomWidgetInterface.
  2. Implement required methods (createWidget, name, group, toolTip, etc.).
  3. Place the plugin Python file in Designer’s plugin directory.
  4. Restart Qt Designer.

Alternatively, you can promote a standard widget in Designer:

  • Place a placeholder QWidget.
  • Right-click → “Promote to…”
  • Set base class name to your custom widget (e.g., ModernButton) and header/module to QT_PyQt_PySide_Custom_Widgets.modern_button.
  • Click “Add” → “Promote”.

Q15. I need to modify the default QSS themes. Where should I put my custom styles?​

Always place your custom QSS or SCSS inside the qss/ or scss/ directory in your project structure created by Project Maker. For example:

project/
 ├── qss/
 │   └── custom_theme.qss
 ├── json_styles/
 │   └── style_config.json

Then update the JSON to include:

{
  "Theme": "Dark",
  "QssFile": "qss/custom_theme.qss",
  "LiveCompileQss": true
}

You can use "LiveCompileQss": true to automatically reload styles while running. This allows real-time UI theming without restarting your app.

Q16. Why does my app freeze when I update UI elements from background threads?​

Qt requires all UI changes to occur in the main thread. If you update widgets directly from a background thread, the GUI may freeze or crash. To fix:

  • Use QThread and emit signals to the main thread:
from PySide6.QtCore import QObject, QThread, Signal

class Worker(QObject):
    finished = Signal(str)
    def run(self):
        result = "done"
        self.finished.emit(result)
  • Connect the signal to your widget’s slot:
worker.finished.connect(self.label.setText)

Your BackendWorker system in the module already uses this pattern safely.

Q17. Can I embed the module’s widgets in a QML-based UI?​

Yes, but you must wrap them in a QQuickWidget or QWidget.createWindowContainer() call. Example:

from PySide6.QtQuickWidgets import QQuickWidget
quick = QQuickWidget()
quick.setSource(QUrl("main.qml"))
layout.addWidget(quick)

Embedding QWidget-based custom widgets inside QML is not recommended for complex UIs, but possible with proper layering and transparent backgrounds.

Q18. How do I integrate this module into an existing project without changing my folder structure?​

Use the CustomWidgets.ProjectMaker only as a reference. You can:

  1. Copy the relevant folders manually (json_styles, qss, generated-files, etc.).
  2. Update imports to use absolute paths, e.g.:
from QT_PyQt_PySide_Custom_Widgets.widgets import ModernButton
  1. Ensure your .env or config includes:
CUSTOM_WIDGETS_PATH=/path/to/QT_PyQt_PySide_Custom_Widgets

Then in your code:

sys.path.append(os.getenv("CUSTOM_WIDGETS_PATH"))

This method avoids refactoring legacy projects.

The recommended layout (as auto-created by Project Maker):

project_name/
 ├── ui/
 ├── src/
 ├── logs/
 ├── qss/
 ├── json_styles/
 ├── generated-files/
 ├── icons/
 ├── main.py

Advantages:

  • Separation of generated code and logic (ui/ vs src/).
  • Easier UI regeneration without losing your logic code.
  • Cleaner imports and reusable components. You can extend this structure with your backend/, database/, or services/ modules as needed.

Q20. Can I use the module with SQLCipher, Firebase, or REST APIs in the same project?​

Yes. The module is purely GUI-based and independent of the backend layer. It is fully compatible with:

  • SQLCipher (for encrypted databases).
  • REST API clients (Requests, HTTPX, aiohttp).
  • Firebase, Supabase, or custom cloud backends. Simply separate your business logic from the GUI code (e.g., backend/ folder) and connect through signals or controllers. This architecture ensures responsive UI updates and thread-safe operations.