qt-packaging

Packaging Qt Python Applications

PyInstaller (most common)

Critical: Virtual Environment Isolation

The official Qt for Python docs document a known PyInstaller gotcha: if a system-level PySide6 is installed, PyInstaller silently picks it instead of your venv version. Before building:

# Remove ALL system-level PySide6 installs from the build machine
pip uninstall pyside6 pyside6_essentials pyside6_addons shiboken6 -y

# Verify only venv version remains
python -c "import PySide6; print(PySide6.__file__)"
# Must show a path inside .venv/, not /usr/lib or system site-packages

--onefile limitation: For Qt6, --onefile bundles cannot deploy Qt plugins automatically. The one-directory (dist/MyApp/) approach is reliable. Use --onefile only if you understand its limitations and handle Qt plugins manually.