Visitar URL original
Route GUI Qt imports through qtpy, keeping PySide6 preferred by C-Achard · Pull Request #3490 · DeepLabCut/DeepLabCut · GitHub
Skip to content

Route GUI Qt imports through qtpy, keeping PySide6 preferred #3490

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
C-Achard wants to merge 16 commits into
base: dev
Choose a base branch
from
Draft

Route GUI Qt imports through qtpy, keeping PySide6 preferred #3490

Changes from 1 commit
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
f08fe7f
Add qtpy to pyproject.toml
C-Achard Sep 7, 2026
edd8a19
Change PySide6 imports for qtpy
C-Achard Sep 7, 2026
bc8f1d1
Improve GUI Qt binding selection
C-Achard Sep 7, 2026
f28174d
Improve GUI Qt binding import error message
C-Achard Sep 7, 2026
13dff38
Use matplotlib qtagg backend in GUI
C-Achard Sep 7, 2026
42c9acb
Avoid QT_API override in darkstyle loading
C-Achard Sep 7, 2026
25fe8cd
Update Qt app exec call
C-Achard Sep 7, 2026
12ff06a
Guard the GUI entry point against binding selection failures
C-Achard Sep 7, 2026
6a805f1
Remove incorrect comment
C-Achard Sep 7, 2026
0c45373
Update uv.lock
C-Achard Sep 8, 2026
a419a77
Import actual qt object imported by dlc instead of global
C-Achard Sep 8, 2026
73ac997
Update tests to use qtpy
C-Achard Sep 8, 2026
95db17c
Remove user-facing GPL Qt binding warning
C-Achard Sep 8, 2026
986a612
Raise the matplotlib floor to 3.5
C-Achard Sep 8, 2026
f247da8
Use exec_ for GUI app startup
C-Achard Sep 8, 2026
bceedc0
Exit CLI on GUI import failures
C-Achard Sep 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Improve GUI Qt binding import error message 
Replace the static missing-Qt message with a dynamic helper that distinguishes between PySide6 not being installed and PySide6 failing to load. The new ImportError text now includes concrete recovery steps (`deeplabcut[gui]` install vs force-reinstall), shows the active Python executable to help diagnose environment mismatches, suggests activating the expected conda env, and links to installation docs.
  • Loading branch information
@C-Achard
C-Achard committed Sep 7, 2026
commit f28174d5f3b3465c15db24fc14fe0fb2d39e5b36
34 changes: 26 additions & 8 deletions deeplabcut/gui/__init__.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,13 +31,31 @@
_VALID_QT_APIS = tuple(api for _, api in _MODULE_TO_QT_API)
_GPL_QT_APIS = ("pyqt5", "pyqt6")

_NO_BINDING_MESSAGE = (
"The DeepLabCut GUI requires a Qt binding, but none could be imported. "
"PySide6 is the supported binding; install the GUI dependencies with "
"`pip install 'deeplabcut[gui]'`. "
"If PySide6 is already installed, it could not be loaded: on Linux this "
"usually means the Qt system libraries are missing."
)
_INSTALL_DOCS_URL = "https://deeplabcut.github.io/DeepLabCut/docs/installation.html"


def _no_binding_message() -> str:
if find_spec("PySide6") is None:
cause = (
"The DeepLabCut GUI could not start: the graphics libraries it needs are not installed.\n\n"
"Install the GUI dependencies with\n"
" pip install 'deeplabcut[gui]'"
)
else:
cause = (
"The DeepLabCut GUI could not start: PySide6 is installed but could not be loaded.\n\n"
"The installation is likely incomplete. Try\n"
" pip install --force-reinstall pyside6"
)

return (
f"{cause}\n\n"
f"Python currently in use:\n {sys.executable}\n\n"
"If that is not the environment you expected, activate the correct conda environment "
"(for example `conda activate DEEPLABCUT`) and try again.\n\n"
f"Installation help: {_INSTALL_DOCS_URL}"
)


_user_qt_api = (os.environ.get("QT_API") or "").lower()
if _user_qt_api and _user_qt_api not in _VALID_QT_APIS:
Expand All @@ -58,7 +76,7 @@
try:
import qtpy # noqa: F401 imported side effect: binding selection
except ImportError as err:
raise ImportError(_NO_BINDING_MESSAGE) from err
raise ImportError(_no_binding_message()) from err

# qtpy rewrites QT_API to the binding it actually loaded, but be explicit:
# matplotlib's backends/qt_compat.py also reads QT_API and must not end up on a
Expand Down